@vestra-player/sdk 1.5.4 → 1.5.6

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.5.6
+
+**A reference for AI assistants.** Documentation and packaging only; no API change, `apiVersion` stays `vestra/1`. (1.5.5 was not published to npm; this release includes its changes.)
+
+- **`llms.txt` and `llms-full.txt`** ([llmstxt.org](https://llmstxt.org)) in the package, exported as `@vestra-player/sdk/llms.txt` and `@vestra-player/sdk/llms-full.txt` (in `node_modules/@vestra-player/sdk/`), and on the documentation site (`https://vestrasys.github.io/vestra-player-sdk/llms.txt`). For Vestra Player AI and other assistants that write plugins.
+  - `llms.txt` (about 10 KB): what a plugin is, the rules, the folder layout, a manifest with every field and the manifest limits, `activate`, every capability, a `TestHost` test, the command line, the common error codes, and the line numbers of each topic in the full file.
+  - `llms-full.txt` (about 300 KB): the guides (Getting started, the UI concept page, both how-tos), every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its description and its `@capability`, `@player`, `@param`, `@returns`, `@throws` and `@deprecated` tags, the internal types the API refers to, and each example's README, walkthrough and complete source (TypeScript, Slint, tests).
+  - Generated from the sources by `npm run docs:llms` (`scripts/llms.mjs`); CI fails when the committed files are stale.
+- **Getting started**: a "Rules for plugins" section (only the public SDK, `import type`, no other plugins, no system commands, macOS and Windows, your own id) and a manifest with every field.
+- `scripts/check-pack.mjs` allows the two files and checks that they name the package version; the install smoke test resolves both exports.
+
+## 1.5.5
+
+**Reserved `vestra.` ids** (player 0.4.1). Documentation only; no API change, `apiVersion` stays `vestra/1`.
+
+- Only the plugins built into the player are official plugins; the ids `vestra` and `vestra.*` (any case) are reserved for them. Every other plugin is a third-party plugin, including those hosted in the official plugin repository, and uses `<GitHub user or organization>.<plugin name>`.
+- `PluginError` lists the code `reserved`: `packages.validate`, `packages.validateArchive`, `PackageCandidate.trial` and `PackageCandidate.install` refuse a package with a reserved id. Development loads (`vestra-player --plugin DIR`) still accept one, with a warning, so built-in plugins can be developed; they are never installed.
 ## 1.5.4
 
 **Markdown in list rows** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.3 need no change.

package/README.md

@@ -12,7 +12,8 @@
   <a href="https://vestrasys.github.io/vestra-player-sdk/">Documentation</a> ·
   <a href="https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html">Getting started</a> ·
   <a href="https://github.com/vestrasys/vestra-player-sdk/tree/main/examples">Examples</a> ·
-  <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a>
+  <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a> ·
+  <a href="https://vestrasys.github.io/vestra-player-sdk/llms.txt">llms.txt</a>
 </p>
 ## Features
 
@@ -21,6 +22,7 @@
 - **Tests without the player**: `@vestra-player/sdk/testing` runs your plugin against an in-memory host with `node --test`.
 - **One command line tool**, `vestra-plugin`, to check, test, build and pack a `.vxp` package.
 - **The same API on macOS and Windows**; every plugin runs in its own Node.js 26 process that the player ships.
+- **A reference for AI assistants**: [`llms.txt`](https://vestrasys.github.io/vestra-player-sdk/llms.txt) (short index) and [`llms-full.txt`](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt) (every declaration, the guides and the examples), also in the package as `@vestra-player/sdk/llms.txt` and `@vestra-player/sdk/llms-full.txt`.
 
 ## Install
 

package/dist/plugin/types.d.ts

@@ -75,6 +75,7 @@ export interface Disposable {
  * | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
  * | `cleanup` | {@link PackageTrial.stop} could not confirm cleanup; call it again. |
  * | `limit` | A player-wide limit was reached (for example the number of commands). |
+ * | `reserved` | {@link Packages.validate}, {@link PackageCandidate.trial}, {@link PackageCandidate.install}: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
  * | `versionMismatch` | The package needs a newer player (`minPlayerVersion`) or another `apiVersion`. |
  * | `ui-prepare` | The player could not prepare a mounted panel or a settings page (its Slint file does not compile, a bound property is not declared, or another plugin's panel holds the slot); `message` has the diagnostics. |
  * | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. |
@@ -4083,13 +4084,18 @@ export interface PackageCandidate {
     readonly manifest: PackageManifest;
     /** The checks the player ran. */
     readonly checks: string[];
-    /** Load it temporarily alongside the installed plugins. */
+    /**
+     * Load it temporarily alongside the installed plugins. A reserved id
+     * (`vestra.*`) fails with `reserved`.
+     */
     trial(): Promise<PackageTrial>;
     /**
      * Install it. The same source upgrades the installed plugin (its data
      * stays); another source fails with `conflict` unless `replace` is set;
      * a built-in id fails with `unsupported` (built-ins update with the
-     * player).
+     * player). A reserved id (`vestra` or `vestra.*`, which every built-in
+     * uses) fails with `reserved` (player 0.4.1; already when validated), as
+     * only the player installs built-in plugins.
      */
     install(options?: InstallOptions): Promise<PackageChange>;
 }
@@ -4197,12 +4203,17 @@ export interface PluginWarning {
  * ```
  */
 export interface Packages {
-    /** Validate a package directory (`plugins.manage`). */
+    /**
+     * Validate a package directory (`plugins.manage`). A package whose id is
+     * reserved for the built-in plugins (`vestra` or `vestra.*`) fails with
+     * `reserved` (player 0.4.1).
+     */
     validate(directory: string): Promise<PackageCandidate>;
     /**
      * Validate a `.vxp` package file (`plugins.manage`, player 0.2.0): the
      * same checks as {@link Packages.validate} after unpacking. Check the
-     * file's sha256 yourself before calling when you know it.
+     * file's sha256 yourself before calling when you know it. A reserved id
+     * fails with `reserved`, as in {@link Packages.validate}.
      */
     validateArchive(file: string): Promise<PackageCandidate>;
     /** Restore a plugin's previous version (`plugins.manage`). */