librebot-tools 0.4.12 → 0.4.14

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/README.md CHANGED
@@ -83,6 +83,14 @@ Rules:
83
83
  including custom roles. Omitting the judge disables automatic completion.
84
84
  Export/import preserves the optional judge and omitted role without inventing
85
85
  defaults. Invalid or failed judge output leaves the task open.
86
+ - Optional `upgradeSummary` (one trimmed line of plain text, 1–280 Unicode
87
+ code points, no control or separator characters) with optional
88
+ `upgradePriority` (`action` for a concrete user step, `notable` for a
89
+ material change needing no step). The priority requires a summary; omit
90
+ both for releases without user-visible changes. The same rules are exported
91
+ as `validateUpgradeNote(summary, priority)` from `librebot-tools/contract`
92
+ for platform validation and Git history. Server-resolved `sourceCommit` /
93
+ `sourceTag` are never source fields and are never exported.
86
94
  - `knowledge/README.md` is the index, not an entry. Every other file under
87
95
  `knowledge/` is one knowledge asset: UTF-8 text inlines as `content`;
88
96
  anything else is returned as an `assets[]` entry
@@ -148,11 +156,14 @@ import {
148
156
  `isModelRoleId`, plus `REPO_CAPABILITIES`, `GITREPO_TRIGGER_EVENT_TYPES`,
149
157
  `WHATSAPP_CAPABILITIES`, `WHATSAPP_TRIGGER_EVENT_TYPES`,
150
158
  `GOOGLE_ACTION_KINDS`, `GOOGLE_DOCS_CAPABILITIES`,
151
- `GOOGLE_SHEETS_CAPABILITIES`, `GOOGLE_CALENDAR_CAPABILITIES` (frozen arrays), and
152
- the derived `ModelRoleId` (generic string: built-in or custom),
159
+ `GOOGLE_SHEETS_CAPABILITIES`, `GOOGLE_CALENDAR_CAPABILITIES` (frozen arrays),
160
+ `UPGRADE_PRIORITIES`, `MAX_UPGRADE_SUMMARY_CODEPOINTS`, and
161
+ `validateUpgradeNote(summary, priority)` (throws a field-specific Error;
162
+ shared with platform validation and Git history), and the derived
163
+ `ModelRoleId` (generic string: built-in or custom),
153
164
  `BuiltInModelRoleId`, `RepoCapability`, `WhatsAppCapability`,
154
165
  `GoogleActionKind`, `GoogleDocsCapability`, `GoogleSheetsCapability`,
155
- `GoogleCalendarCapability`,
166
+ `GoogleCalendarCapability`, `UpgradePriority`,
156
167
  `GitrepoTriggerEventType`, and `WhatsAppTriggerEventType` types. The root
157
168
  entry re-exports the same values.
158
169
  - No author-configured shell commands are executed. Standard skill
@@ -280,17 +291,35 @@ The npm package's Trusted Publisher must authorize organization `librebot-work`,
280
291
  repository `tools`, workflow filename `publish.yml`, with direct `npm publish`
281
292
  allowed and no environment name.
282
293
 
283
- After the compatible platform contract is ready, commit the version change and
284
- lockfile, merge it to `main`, then push a matching stable version tag:
294
+ Publish every tools release to npm through this workflow. A Git tag or local
295
+ tarball is not a distribution channel for Librebot or bot authors.
285
296
 
286
- ```sh
287
- git tag v0.4.7
288
- git push origin v0.4.7
289
- ```
297
+ 1. Update `package.json` and `package-lock.json` to a new stable version
298
+ (`npm version <version> --no-git-tag-version`), then run `npm ci --ignore-scripts`,
299
+ `npm test`, and `npm pack --dry-run`. Commit and merge the release to `main`.
300
+ 2. Fetch `origin/main` and tag the merged release commit, not a local draft.
301
+ For example, if the tip of `main` is the `0.4.13` release:
302
+
303
+ ```sh
304
+ git fetch origin main
305
+ git tag v0.4.13 origin/main
306
+ git push origin refs/tags/v0.4.13
307
+ ```
308
+
309
+ 3. Check the **Publish npm package** workflow for the tag. It verifies the
310
+ tag and its ancestry, tests and inspects the package, then publishes it.
311
+ Before updating platform pins or announcing the release, verify npm serves
312
+ the version and `latest` points to it:
313
+
314
+ ```sh
315
+ npm view librebot-tools@0.4.13 version --prefer-online
316
+ npm view librebot-tools dist-tags --json --prefer-online
317
+ ```
318
+
319
+ Do not run `npm login` or `npm publish` locally. If CI reports success but
320
+ the registry does not yet serve the release, verify registry availability
321
+ before trying to publish again; npm versions are immutable.
290
322
 
291
- Use the new package version, not an already published version. The workflow
292
- requires the tag to match `package.json` and point to a commit reachable from
293
- `main`, installs dependencies, runs tests, inspects the package, and publishes.
294
323
  Protect `main` and restrict creation/update/deletion of `v*` tags to release
295
324
  maintainers: pushing a release tag authorizes publishing. npm trusted publisher
296
325
  setup must complete its first successful publish within two days; otherwise
@@ -317,9 +346,13 @@ recreate that configuration when a release is ready.
317
346
  `edit_event`, `cancel_event`, `manage_attendees`). Capability namespaces are
318
347
  exclusive to their kind. Content and style are separate grants: Docs
319
348
  `edit_document_content` covers text insertion, replacement, and deletion via
320
- `google_edit_document`, while `format_document` covers text and named
321
- heading styles via `google_format_document`; Sheets keeps literal
322
- `write_values`, `write_formulas`, and `format_cells` as separate grants.
349
+ `google_edit_document`, while `format_document` covers Docs formatting via
350
+ `google_format_document`, which takes native `updateTextStyle` /
351
+ `updateParagraphStyle` requests with exact reviewed `fields` masks, one
352
+ explicit tab, and the read revision; a batch containing anything outside
353
+ formatting (links, content, or structural requests) is refused in full.
354
+ Sheets keeps literal `write_values`, `write_formulas`, and `format_cells`
355
+ as separate grants.
323
356
  Drive bindings are account-wide; calendar bindings pin exact calendar IDs
324
357
  with attendee/notification policy in owner instance settings, never
325
358
  portable source. The broad Docs `edit_document` grant is removed: sources
@@ -341,7 +374,10 @@ recreate that configuration when a release is ready.
341
374
  same action group); 0.4.12 replaces the broad Docs `edit_document` grant
342
375
  with separate `edit_document_content` (text edits) and `format_document`
343
376
  (text and named heading styles) grants, and adds the Sheets `format_cells`
344
- grant for cell colors independent of value and formula writes.
377
+ grant for cell colors independent of value and formula writes; 0.4.13 adds
378
+ the optional `upgradeSummary` release note with `upgradePriority`
379
+ (`action` | `notable`, requires a summary) and the shared
380
+ `validateUpgradeNote` contract helper.
345
381
  - Portable WhatsApp triggers use `kind: whatsapp`, semantic `message.created`
346
382
  and/or `reaction.changed`, and the existing keyed decider definition fields.
347
383
  Event namespaces are checked against the selected trigger kind.
@@ -351,17 +387,10 @@ recreate that configuration when a release is ready.
351
387
  - `BotConnector.endpoint?` (remote MCP): the runtime must validate the
352
388
  bound connection's endpoint matches the declared endpoint.
353
389
 
354
- ## Development and publishing
355
-
356
- Node.js 24 or newer is required. From this repository, install the locked
357
- dependencies, run the tests, and inspect the package before publishing:
390
+ ## Development
358
391
 
359
- ```sh
360
- npm ci
361
- npm test
362
- npm pack --dry-run
363
- npm publish --access public
364
- ```
392
+ Node.js 24 or newer is required. Use `npm ci --ignore-scripts` and `npm test`
393
+ for local development. Follow [Publishing](#publishing) for releases.
365
394
 
366
395
  ## Tests
367
396
 
package/bin/librebot.js CHANGED
@@ -122,6 +122,7 @@ async function cmdPreview(dir, json) {
122
122
  const { draft } = result;
123
123
  console.log(`# ${draft.name}`);
124
124
  console.log(`${draft.description}\n`);
125
+ if (draft.upgradeSummary) console.log(`release note${draft.upgradePriority ? ` [${draft.upgradePriority}]` : ""}: ${draft.upgradeSummary}`);
125
126
  console.log(`prompt: instructions.md (${draft.botPrompt.length} chars)`);
126
127
  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}`);
127
128
  console.log(`roles: ${draft.modelRoles.map((r) => r.role).join(", ")}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "librebot-tools",
3
- "version": "0.4.12",
3
+ "version": "0.4.14",
4
4
  "description": "Public source-format tooling for Librebot bots: parse, validate, preview, scaffold, and skill-lock resolution.",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -6,10 +6,22 @@
6
6
  "type": "object",
7
7
  "additionalProperties": false,
8
8
  "required": ["formatVersion", "name", "description", "modelRoles"],
9
+ "dependentRequired": { "upgradePriority": ["upgradeSummary"] },
9
10
  "properties": {
10
11
  "formatVersion": { "const": 1 },
11
12
  "name": { "type": "string", "minLength": 1, "maxLength": 100 },
12
13
  "description": { "type": "string", "minLength": 1, "maxLength": 1000 },
14
+ "upgradeSummary": {
15
+ "type": "string",
16
+ "minLength": 1,
17
+ "maxLength": 280,
18
+ "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+(?![\\s\\S])",
19
+ "description": "Author-written release note for the next publish: one trimmed line of plain text, 1-280 Unicode code points, no control or separator characters. Omit for releases without user-visible changes. Semantic validation trims surrounding whitespace, counts code points, and rejects multi-line or control content."
20
+ },
21
+ "upgradePriority": {
22
+ "enum": ["action", "notable"],
23
+ "description": "Highlights the upgradeSummary: action for a concrete user step, notable for a material change needing no step. Requires upgradeSummary."
24
+ },
13
25
  "icon": {
14
26
  "type": "string",
15
27
  "minLength": 1,
package/src/contract.d.ts CHANGED
@@ -42,3 +42,8 @@ export type GoogleActionKind = typeof GOOGLE_ACTION_KINDS[number];
42
42
  export type GoogleDocsCapability = typeof GOOGLE_DOCS_CAPABILITIES[number];
43
43
  export type GoogleSheetsCapability = typeof GOOGLE_SHEETS_CAPABILITIES[number];
44
44
  export type GoogleCalendarCapability = typeof GOOGLE_CALENDAR_CAPABILITIES[number];
45
+ export const UPGRADE_PRIORITIES: readonly ["action", "notable"];
46
+ export const MAX_UPGRADE_SUMMARY_CODEPOINTS: 280;
47
+ export function validateUpgradeNote(summary: unknown, priority: unknown): void;
48
+
49
+ export type UpgradePriority = typeof UPGRADE_PRIORITIES[number];
package/src/contract.js CHANGED
@@ -76,3 +76,45 @@ export const GOOGLE_ACTION_KINDS = Object.freeze(["google_docs", "google_sheets"
76
76
  export const GOOGLE_DOCS_CAPABILITIES = Object.freeze(["search_documents", "read_document", "create_document", "edit_document_content", "format_document"]);
77
77
  export const GOOGLE_SHEETS_CAPABILITIES = Object.freeze(["search_spreadsheets", "read_spreadsheet", "create_spreadsheet", "write_values", "append_values", "write_formulas", "format_cells"]);
78
78
  export const GOOGLE_CALENDAR_CAPABILITIES = Object.freeze(["search_events", "read_event", "create_event", "edit_event", "cancel_event", "manage_attendees"]);
79
+
80
+ // Author-written release note for the next publish: one trimmed line of
81
+ // plain text (1-280 Unicode code points). `upgradePriority` ("action" for a
82
+ // concrete user step, "notable" for a material change needing no step)
83
+ // requires a summary. Both fields are optional; releases without
84
+ // user-visible changes omit them. Server-resolved `sourceCommit`/`sourceTag`
85
+ // are never author input. Shared with platform validation and Git history
86
+ // so every surface enforces identical rules; platform catches the thrown
87
+ // Error as badRequest.
88
+ export const UPGRADE_PRIORITIES = Object.freeze(["action", "notable"]);
89
+ export const MAX_UPGRADE_SUMMARY_CODEPOINTS = 280;
90
+ // C0/C1 controls, line/paragraph separators: single-line plain text only.
91
+ const UPGRADE_SUMMARY_CONTROL_RE = new RegExp("[" + String.fromCharCode(0) + "-" + String.fromCharCode(31) + String.fromCharCode(127) + "-" + String.fromCharCode(159) + String.fromCharCode(8232) + String.fromCharCode(8233) + "]");
92
+ /**
93
+ * Validate an author-written upgrade note. Throws an Error whose message
94
+ * names the offending field (`upgradeSummary` or `upgradePriority`).
95
+ * @param {unknown} summary
96
+ * @param {unknown} priority
97
+ */
98
+ export function validateUpgradeNote(summary, priority) {
99
+ if (summary === undefined) {
100
+ if (priority === undefined) return;
101
+ throw new Error("upgradePriority requires upgradeSummary");
102
+ }
103
+ if (typeof summary !== "string") {
104
+ throw new Error("upgradeSummary must be a string");
105
+ }
106
+ const trimmed = summary.trim();
107
+ if (!trimmed) {
108
+ throw new Error("upgradeSummary must not be empty");
109
+ }
110
+ if ([...trimmed].length > MAX_UPGRADE_SUMMARY_CODEPOINTS) {
111
+ throw new Error(`upgradeSummary must be at most ${MAX_UPGRADE_SUMMARY_CODEPOINTS} characters`);
112
+ }
113
+ if (UPGRADE_SUMMARY_CONTROL_RE.test(trimmed)) {
114
+ throw new Error("upgradeSummary must be single-line plain text without control or separator characters");
115
+ }
116
+ if (priority === undefined) return;
117
+ if (priority !== "action" && priority !== "notable") {
118
+ throw new Error('upgradePriority must be "action" or "notable"');
119
+ }
120
+ }
package/src/index.d.ts CHANGED
@@ -54,7 +54,12 @@ export interface BotCompletionJudge {
54
54
  modelRole?: ModelRoleId;
55
55
  }
56
56
 
57
- export interface BotDraft {
57
+ export interface BotUpgradeText {
58
+ upgradeSummary?: string;
59
+ upgradePriority?: "action" | "notable";
60
+ }
61
+
62
+ export interface BotDraft extends BotUpgradeText {
58
63
  name: string;
59
64
  description: string;
60
65
  botPrompt: string;
@@ -71,7 +76,6 @@ export interface BotDraft {
71
76
  actions: Array<{ key: string; kind: "gitrepo"; label?: string; capabilities: RepoCapability[] } | { key: string; kind: "whatsapp"; label?: string; capabilities: WhatsAppCapability[] } | { key: string; kind: "google_docs"; label?: string; capabilities: GoogleDocsCapability[] } | { key: string; kind: "google_sheets"; label?: string; capabilities: GoogleSheetsCapability[] } | { key: string; kind: "google_calendar"; label?: string; capabilities: GoogleCalendarCapability[] }>;
72
77
  icon?: string;
73
78
  }
74
-
75
79
  export interface KnowledgeAsset {
76
80
  knowledgeId: string;
77
81
  path: string;
package/src/index.js CHANGED
@@ -51,9 +51,11 @@ export {
51
51
  CUSTOM_MODEL_ROLE_ID_RE,
52
52
  FORMAT_VERSION,
53
53
  MAX_MODEL_ROLES,
54
+ MAX_UPGRADE_SUMMARY_CODEPOINTS,
54
55
  MODEL_ROLES,
55
56
  REPO_CAPABILITIES,
56
57
  RESERVED_MODEL_ROLE_IDS,
58
+ UPGRADE_PRIORITIES,
57
59
  GITREPO_TRIGGER_EVENT_SOURCES,
58
60
  GITREPO_TRIGGER_EVENT_TYPES,
59
61
  GOOGLE_ACTION_KINDS,
@@ -66,5 +68,6 @@ export {
66
68
  isCustomModelRoleId,
67
69
  isModelRoleId,
68
70
  isReservedModelRoleId,
71
+ validateUpgradeNote,
69
72
  } from "./contract.js";
70
73
  export { validateKnowledgeSources, validateRequirements } from "./validate.js";
package/src/parse.js CHANGED
@@ -11,7 +11,7 @@ import { checkSourcesLock, parseSourcesYaml } from "./skills-lock.js";
11
11
  import { sha256Hex, toBytes } from "./util.js";
12
12
  import { vendorContentHash } from "./skills-import.js";
13
13
  import { iconPath, validateIcon } from "./icon.js";
14
- import { FORMAT_VERSION } from "./contract.js";
14
+ import { FORMAT_VERSION, validateUpgradeNote } from "./contract.js";
15
15
  import {
16
16
  entryId,
17
17
  requiredString,
@@ -38,6 +38,8 @@ const TOP_LEVEL_KEYS = [
38
38
  "formatVersion",
39
39
  "name",
40
40
  "description",
41
+ "upgradeSummary",
42
+ "upgradePriority",
41
43
  "icon",
42
44
  "modelRoles",
43
45
  "completionJudge",
@@ -271,6 +273,23 @@ export async function validateFiles(input) {
271
273
  sink,
272
274
  FILE_BOT_YAML,
273
275
  );
276
+ // Author-written release note for the next publish. Shared rules live in
277
+ // contract.validateUpgradeNote; the trimmed summary is what the draft and
278
+ // export carry. Server-resolved sourceCommit/sourceTag are never source.
279
+ let upgradeSummary;
280
+ let upgradePriority;
281
+ try {
282
+ validateUpgradeNote(botDoc.upgradeSummary, botDoc.upgradePriority);
283
+ if (typeof botDoc.upgradeSummary === "string") upgradeSummary = botDoc.upgradeSummary.trim();
284
+ if (botDoc.upgradePriority === "action" || botDoc.upgradePriority === "notable") upgradePriority = botDoc.upgradePriority;
285
+ } catch (error) {
286
+ const message = error instanceof Error ? error.message : String(error);
287
+ errors.push({
288
+ file: FILE_BOT_YAML,
289
+ field: message.startsWith("upgradePriority") ? "upgradePriority" : "upgradeSummary",
290
+ message,
291
+ });
292
+ }
274
293
  let icon;
275
294
  if (botDoc.icon !== undefined) {
276
295
  try {
@@ -597,6 +616,8 @@ export async function validateFiles(input) {
597
616
  const draft = {
598
617
  name,
599
618
  description,
619
+ ...(upgradeSummary !== undefined ? { upgradeSummary } : {}),
620
+ ...(upgradePriority !== undefined ? { upgradePriority } : {}),
600
621
  ...(icon ? { icon: `./${icon.path}` } : {}),
601
622
  botPrompt,
602
623
  readme,
package/src/scaffold.js CHANGED
@@ -4,6 +4,7 @@
4
4
  import { mkdir, readdir, writeFile } from "node:fs/promises";
5
5
  import { join } from "node:path";
6
6
  import { stringify as stringifyYaml } from "yaml";
7
+ import { validateUpgradeNote } from "./contract.js";
7
8
  import { toBytes } from "./util.js";
8
9
  import { DEFAULT_ICON, iconPath, validateIcon } from "./icon.js";
9
10
 
@@ -127,6 +128,10 @@ export function exportBotFiles(
127
128
  if (typeof draft.readme !== "string" || !draft.readme.trim()) {
128
129
  throw new Error("export requires a non-empty draft readme");
129
130
  }
131
+ // Author-written release note only: invalid notes fail export, and
132
+ // server-resolved sourceCommit/sourceTag (or visibility) on a stored Bot
133
+ // are never written back to source.
134
+ validateUpgradeNote(draft.upgradeSummary, draft.upgradePriority);
130
135
  const readme = draft.readme.trim();
131
136
  if (readme.length > 100000) {
132
137
  throw new Error("draft readme is too long (max 100000 chars)");
@@ -177,6 +182,8 @@ export function exportBotFiles(
177
182
  formatVersion: 1,
178
183
  name,
179
184
  description: description ?? "",
185
+ ...(typeof draft.upgradeSummary === "string" ? { upgradeSummary: draft.upgradeSummary.trim() } : {}),
186
+ ...(draft.upgradePriority === "action" || draft.upgradePriority === "notable" ? { upgradePriority: draft.upgradePriority } : {}),
180
187
  ...(draft.icon !== undefined ? { icon: `./${iconPath(draft.icon)}` } : {}),
181
188
  modelRoles: modelRoles ?? [{ role: "default", label: "Main" }],
182
189
  ...(draft.completionJudge !== undefined ? { completionJudge: draft.completionJudge } : {}),
@@ -0,0 +1,142 @@
1
+ // Upgrade notes: author-written release note shared with platform
2
+ // validation (contract.validateUpgradeNote) and Git history.
3
+
4
+ import { describe, it } from "node:test";
5
+ import assert from "node:assert/strict";
6
+ import {
7
+ exportBotFiles,
8
+ loadSchema,
9
+ parseBotFiles,
10
+ validateFiles,
11
+ validateUpgradeNote,
12
+ } from "../src/index.js";
13
+
14
+ const base = (yaml) =>
15
+ validateFiles({
16
+ "bot.yaml":
17
+ "formatVersion: 1\nname: T\ndescription: D\nmodelRoles:\n - role: default\n label: Main\n" +
18
+ yaml,
19
+ "instructions.md": "Be helpful.",
20
+ "README.md": "# T",
21
+ });
22
+
23
+ describe("validateUpgradeNote contract", () => {
24
+ it("accepts absence, a lone summary, and both priorities", () => {
25
+ assert.doesNotThrow(() => validateUpgradeNote(undefined, undefined));
26
+ assert.doesNotThrow(() => validateUpgradeNote("Drops SMS support.", undefined));
27
+ assert.doesNotThrow(() => validateUpgradeNote("Drops SMS support.", "action"));
28
+ assert.doesNotThrow(() => validateUpgradeNote("Drops SMS support.", "notable"));
29
+ });
30
+
31
+ it("rejects a priority without a summary", () => {
32
+ assert.throws(() => validateUpgradeNote(undefined, "action"), /upgradeSummary/);
33
+ assert.throws(() => validateUpgradeNote(undefined, "notable"), /upgradeSummary/);
34
+ });
35
+
36
+ it("rejects empty, blank, and non-string summaries", () => {
37
+ assert.throws(() => validateUpgradeNote("", undefined), /upgradeSummary/);
38
+ assert.throws(() => validateUpgradeNote(" ", undefined), /upgradeSummary/);
39
+ assert.throws(() => validateUpgradeNote(42, undefined), /upgradeSummary/);
40
+ });
41
+
42
+ it("counts 280 Unicode code points, not UTF-16 units", () => {
43
+ assert.doesNotThrow(() => validateUpgradeNote("🔔".repeat(280), undefined));
44
+ assert.throws(() => validateUpgradeNote("🔔".repeat(281), undefined), /upgradeSummary/);
45
+ assert.doesNotThrow(() => validateUpgradeNote("a".repeat(280), "notable"));
46
+ assert.throws(() => validateUpgradeNote("a".repeat(281), "notable"), /upgradeSummary/);
47
+ });
48
+
49
+ it("rejects multi-line and control content", () => {
50
+ for (const summary of ["One\nTwo", "One\rTwo", "Has\ttab", "Has" + String.fromCharCode(0) + "control", "One" + String.fromCodePoint(0x2028) + "Two", "One" + String.fromCodePoint(0x2029) + "Two", "One" + String.fromCharCode(0x7f) + "Two"]) {
51
+ assert.throws(() => validateUpgradeNote(summary, undefined), /upgradeSummary/, JSON.stringify(summary));
52
+ }
53
+ });
54
+
55
+ it("rejects unknown priorities", () => {
56
+ assert.throws(() => validateUpgradeNote("Drops SMS support.", "urgent"), /upgradePriority/);
57
+ assert.throws(() => validateUpgradeNote("Drops SMS support.", ""), /upgradePriority/);
58
+ });
59
+ });
60
+
61
+ describe("upgrade notes in source", () => {
62
+ it("parses a trimmed summary and priority into the draft", async () => {
63
+ const result = await base('upgradeSummary: " Drops SMS support. "\nupgradePriority: notable\n');
64
+ assert.equal(result.ok, true);
65
+ assert.equal(result.draft.upgradeSummary, "Drops SMS support.");
66
+ assert.equal(result.draft.upgradePriority, "notable");
67
+ });
68
+
69
+ it("omits both fields when absent", async () => {
70
+ const result = await base("");
71
+ assert.equal(result.ok, true);
72
+ assert.equal("upgradeSummary" in result.draft, false);
73
+ assert.equal("upgradePriority" in result.draft, false);
74
+ });
75
+
76
+ it("blames priority without a summary on upgradePriority", async () => {
77
+ const result = await base("upgradePriority: action\n");
78
+ assert.equal(result.ok, false);
79
+ assert.ok(result.errors.some((e) => e.field === "upgradePriority" && /upgradeSummary/.test(e.message)));
80
+ });
81
+
82
+ it("blames multi-line and over-long summaries on upgradeSummary", async () => {
83
+ const multiline = await base("upgradeSummary: |\n One\n Two\n");
84
+ assert.equal(multiline.ok, false);
85
+ assert.ok(multiline.errors.some((e) => e.field === "upgradeSummary"));
86
+ const emoji = "🔔".repeat(281);
87
+ const long = await base(`upgradeSummary: "${emoji}"\n`);
88
+ assert.equal(long.ok, false);
89
+ assert.ok(long.errors.some((e) => e.field === "upgradeSummary"));
90
+ });
91
+
92
+ it("round-trips the note through export and parse", async () => {
93
+ const parsed = await parseBotFiles({
94
+ ...{
95
+ "bot.yaml":
96
+ "formatVersion: 1\nname: T\ndescription: D\nupgradeSummary: Drops SMS support.\nupgradePriority: action\nmodelRoles:\n - role: default\n label: Main\n",
97
+ "instructions.md": "Be helpful.",
98
+ "README.md": "# T",
99
+ },
100
+ });
101
+ assert.equal(parsed.draft.upgradeSummary, "Drops SMS support.");
102
+ const roundtrip = await parseBotFiles(exportBotFiles(parsed.draft));
103
+ assert.equal(roundtrip.draft.upgradeSummary, "Drops SMS support.");
104
+ assert.equal(roundtrip.draft.upgradePriority, "action");
105
+ });
106
+
107
+ it("never exports server-resolved source fields", async () => {
108
+ const parsed = await parseBotFiles({
109
+ "bot.yaml":
110
+ "formatVersion: 1\nname: T\ndescription: D\nupgradeSummary: Drops SMS support.\nmodelRoles:\n - role: default\n label: Main\n",
111
+ "instructions.md": "Be helpful.",
112
+ "README.md": "# T",
113
+ });
114
+ const withServer = { ...parsed.draft, sourceCommit: "abc123", sourceTag: "v2", visibility: "private" };
115
+ const files = exportBotFiles(withServer);
116
+ assert.doesNotMatch(files["bot.yaml"], /sourceCommit|sourceTag|visibility/);
117
+ assert.match(files["bot.yaml"], /upgradeSummary/);
118
+ });
119
+
120
+ it("throws on export with an invalid note", () => {
121
+ assert.throws(() => exportBotFiles({
122
+ name: "T",
123
+ description: "D",
124
+ botPrompt: "Be helpful.",
125
+ readme: "# T",
126
+ modelRoles: [{ role: "default", label: "Main" }],
127
+ knowledge: [],
128
+ skills: [],
129
+ connectors: [],
130
+ triggers: [],
131
+ workspace: [],
132
+ actions: [],
133
+ upgradePriority: "action",
134
+ }), /upgradeSummary/);
135
+ });
136
+
137
+ it("ships the upgrade properties in the v1 schema", async () => {
138
+ const schema = await loadSchema("v1");
139
+ assert.equal(schema.properties.upgradeSummary.type, "string");
140
+ assert.deepEqual(schema.properties.upgradePriority.enum, ["action", "notable"]);
141
+ });
142
+ });