@vestra-player/sdk 1.5.49 → 1.5.50

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.5.50
+
+**Who must change: tools that read `llms-full.txt`.** It is removed (approved by the maintainer, 2026-11-01): from the package (`@vestra-player/sdk/llms-full.txt`), from the documentation site and from the generators. Read the documentation tree instead: `npx -p @vestra-player/sdk vestra-plugin docs [path]` and `… docs --search <words>`, or `docs(path)` and `searchDocs(query)` from `@vestra-player/sdk/docs` in a program. The player's Workshop vendors the package's `dist/` (the tree is `dist/docs-tree.json.gz`, built with the package; reading it needs nothing else) and must drop its `llms-full.txt` expectation. Plugins need no change: no changes to the plugin API, `apiVersion` stays `vestra/1`, no new capability, no player version needed.
+
+- **The documentation as a tree for agents** (`@vestra-player/sdk/docs`, `vestra-plugin docs`). An agent never gets one large file any more (`llms-full.txt` was 1,032 KiB, half of it the API type dump, too large for an agent to read): it reads the documentation by path, like `go doc`, with the same pages, structure and text as the site. `/` lists Overview (the README), Guides and API; `/Guides/<group>/<page>` is a page of the site (`/Guides/How-to/Test a plugin`; its file name, with or without `.md`, and an old title work too); `/API/<category>/<symbol>/<member>` is one declaration of `@vestra-player/sdk`, `@vestra-player/sdk/testing` or `@vestra-player/sdk/docs` with its import line, signature (and links to the SDK types it names), parameters, return value, errors, capability, minimum player version, since and examples (`/API/Media/Snapshot/dispose`). Every node lists the paths one level down with the site's one-line summary (a page's description, a declaration's first paragraph). Links in the text are paths of the tree (in angle brackets when they have spaces), including the README's links to the site; other repository files link to GitHub; images are left out.
+- **Paths are forgiving.** Case, spaces and punctuation do not matter, the leading `/` is optional, `.` works like `/` (`Snapshot.export`, `plugin.player`), a name alone finds its node at any depth (`TestHost`, `TestHost/settle`; a declaration wins over a guide page of a similar name and an interface over a category of the same name), one stale segment is left out (`/API/Playback/Snapshot/export`), and the whole path is tried against every candidate (`/API/Media/current` finds the interface `Media`'s member, not the category). Several equally good matches are listed, not guessed; a path that matches nothing answers with the nearest names and the level's contents. `#heading` opens the page of a long answer that has the section. In Git Bash, `vestra-plugin docs` undoes the shell's conversion of `/API…` into a Windows path (detected by `MSYSTEM`).
+- **Search** (`searchDocs(query)`, `--search`) lists the nodes containing every word, leaving out common words ("a", "the", "to"); names rank first, a declaration's before a page's, a path that contains every word first of all.
+- **Bounded answers.** Every answer is at most 8 KB (`DOCS_PAGE_BYTES`); a longer one comes in pages (`{ page: 2 }`, `--page 2`). Page 1 lists the sections with the page each starts on; a code block cut by a break is closed and opened again, a short one moves to the next page whole, a cut table repeats its header row.
+- **Built with the package.** `npm run build` (and so `prepare`) converts the project with TypeDoc exactly as the site does (typedoc.json, `scripts/typedoc-plugin.mjs`) and writes `dist/docs-tree.json.gz` (scripts/docs-tree.mjs): 1,137 nodes, about 372 KiB gzipped (1.4 MiB of JSON), read on first use; TypeDoc is needed only to build it. A test checks that every page and every declaration of the site is in the tree, as a node or described in its owner's text.
+- **`llms.txt` is a short entry** (llmstxt.org): what the SDK is, how to read the tree by command line or library, the path scheme, and the tree's top levels with their summaries; about 5 KB, generated from the tree (`npm run docs:llms`).
+- _Docs_: new how-to [Give a coding agent the documentation](docs/how-to/agent-docs.md); [Command line](docs/reference/cli.md) lists `vestra-plugin docs`; the API pages gain `@vestra-player/sdk/docs`; the README and the maintainers' notes point to the tree instead of `llms-full.txt`.
+
 ## 1.5.49
 
 **Who must change: nobody.** No changes to the plugin API (`@vestra-player/sdk/runtime` gains the additive `RuntimeOptions` and an optional sixth `createPlugin` argument), `apiVersion` stays `vestra/1`, no new capability, no player version needed, and the player's runner needs no change. **Behaviour change, approved by the maintainer (2026-11-01):** in the player, a command declaration it refuses during activation no longer fails the whole plugin. What `commands.add` checks itself (an unknown `@` menu id, more than 8 path segments, an `order` out of range, a malformed or repeated binding, a bad `button`, a reason text of the wrong shape) still throws from `add`. A plugin whose `activate` relied on that failure (none is known) now runs without the refused command.

package/README.md

@@ -23,7 +23,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`.
+- **Documentation for coding agents**: `npx -p @vestra-player/sdk vestra-plugin docs [path]` reads this documentation as a tree of short pages, like `go doc` (`… docs Snapshot.export`, `… docs --search <words>`; in a project that depends on the SDK, `npx vestra-plugin docs`); programs import `@vestra-player/sdk/docs`. [`llms.txt`](https://vestrasys.github.io/vestra-player-sdk/llms.txt) (also `@vestra-player/sdk/llms.txt`) is the short entry that explains it.
 
 ## Install
 

package/bin/vestra-plugin.mjs

@@ -6,6 +6,8 @@
  *   vestra-plugin <check|build|test|pack> [plugin-dir...] [--version x.y.z] [--out dir]
  *   vestra-plugin i18n extract [plugin-dir...] [--locale <lang>]...
  *   vestra-plugin i18n check [plugin-dir...]
+ *   vestra-plugin docs [path] [--page N]
+ *   vestra-plugin docs --search <query> [--page N]
  *
  * A plugin directory holds manifest.json; the default is the current
  * directory. Works in any project that depends on @vestra-player/sdk.
@@ -19,6 +21,10 @@
  *   test    node --test on tests/*.test.{ts,mjs}
  *   pack    build, then dist/ → <out>/<id>-<version>.vxp (a zip; default
  *           out: the current directory) with its sha256 and size
+ *   docs    the SDK's documentation by path, for coding agents: `/` lists
+ *           Overview, Guides and API, `/API/Media/Snapshot/dispose` is
+ *           one member's whole documentation; --search <query> lists
+ *           matching paths; at most 8 KB per answer, --page N for the rest
  *
  * Translations (docs/how-to/i18n.md). English is the source text; each
  * language is a gettext file locales/<lang>.po:
@@ -932,8 +938,44 @@ const USAGE = [
   "       vestra-plugin check [plugin-dir...] --json",
   "       vestra-plugin i18n extract [plugin-dir...] [--locale <lang>]...",
   "       vestra-plugin i18n check [plugin-dir...]",
+  "       vestra-plugin docs [path] [--page N]",
+  "       vestra-plugin docs --search <query> [--page N]",
 ].join("\n");
 
+/** `vestra-plugin docs`: `@vestra-player/sdk/docs` on the command line. */
+async function docsCommand(args) {
+  const index = args.indexOf("--page");
+  let page;
+  if (index >= 0) {
+    const [, value] = args.splice(index, 2);
+    page = Number(value);
+    if (!Number.isInteger(page) || page < 1)
+      fail("--page needs a page number (1, 2, …)");
+  }
+  const { docs, searchDocs } = await import(
+    pathToFileURL(join(sdkRoot, "dist/docs.js")).href
+  );
+  const search = args.indexOf("--search");
+  if (search >= 0) {
+    args.splice(search, 1);
+    if (!args.length) fail("--search needs words to search for");
+    console.log(searchDocs(args.join(" "), { page }));
+    return;
+  }
+  // A path with spaces may come as several arguments.
+  let path = args.length ? args.join(" ") : "/";
+  // Git Bash (MSYSTEM) turns "/API/Media" into "<its root>/API/Media":
+  // start again at the tree's top level.
+  if (process.env.MSYSTEM && /^[A-Za-z]:[\\/]/.test(path)) {
+    const segments = path.split(/[\\/]/);
+    const top = segments.findIndex((segment) =>
+      ["overview", "guides", "api"].includes(segment.toLowerCase()),
+    );
+    if (top > 0) path = `/${segments.slice(top).join("/")}`;
+  }
+  console.log(docs(path, { page }));
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args.shift();
@@ -948,6 +990,10 @@ async function main() {
     console.log(USAGE);
     return;
   }
+  if (command === "docs") {
+    await docsCommand(args);
+    return;
+  }
   let subcommand = null;
   if (command === "i18n") {
     subcommand = args.shift();

package/dist/docs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The most bytes (UTF-8) one answer of `docs` or `searchDocs` has.
+ *
+ * @category Docs
+ */
+export declare const DOCS_PAGE_BYTES = 8192;
+/**
+ * Which page of a long answer to return.
+ *
+ * @category Docs
+ */
+export interface DocsOptions {
+    /** 1-based; the default is 1. */
+    page?: number;
+}
+/**
+ * The documentation at `path`: its text, then the paths one level down,
+ * each with a one-line summary.
+ *
+ * `/` lists Overview, Guides and API. `/Guides/<group>/<page title>` is a
+ * page of the documentation site (its file name works too:
+ * `/Guides/How-to/testing`); `/API/<category>/<symbol>/<member>` is a
+ * declaration with its signature, parameters, return value, errors,
+ * capability, player version and examples. Matching ignores case, spaces
+ * and punctuation; a leading `/` and a `.md` suffix are optional; `.`
+ * works like `/` (`Snapshot.export`); a name that is not at its level is
+ * looked up below it (`TestHost`, `/API/Snapshot` finds
+ * `/API/Media/Snapshot`), and one stale segment is skipped. A `#heading`
+ * opens the page of a long answer that has it. A path that matches
+ * nothing answers with the nearest names and the level's contents.
+ *
+ * @param path - Default `/`.
+ * @param options - `page` of a long answer.
+ * @returns At most {@link DOCS_PAGE_BYTES} bytes of text; a continued
+ *   answer ends with the number of the next page.
+ *
+ * @category Docs
+ */
+export declare function docs(path?: string, options?: DocsOptions): string;
+/**
+ * Search the documentation by name and text: the matching paths, best
+ * first, each with its one-line summary. Every word of `query` (common
+ * words such as "a", "the", "to" left out) must occur, in any case, in
+ * the path, the summary or the text; a match in a name ranks first, a
+ * declaration's name before a page's.
+ *
+ * @param query - Words, such as `"snapshot export"` or `"onError"`.
+ * @param options - `page` of a long answer.
+ * @returns At most {@link DOCS_PAGE_BYTES} bytes of text.
+ *
+ * @category Docs
+ */
+export declare function searchDocs(query: string, options?: DocsOptions): string;