@xh/hoist 89.0.0 → 89.1.0

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.
Files changed (68) hide show
  1. package/CHANGELOG.md +61 -5
  2. package/appcontainer/MessageModel.ts +11 -10
  3. package/appcontainer/README.md +6 -2
  4. package/build/types/appcontainer/MessageModel.d.ts +4 -1
  5. package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
  6. package/build/types/core/XH.d.ts +7 -6
  7. package/build/types/core/model/HoistModel.d.ts +1 -0
  8. package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
  9. package/build/types/data/cube/View.d.ts +0 -2
  10. package/build/types/data/cube/impl/RowCache.d.ts +1 -1
  11. package/build/types/data/cube/row/BaseRow.d.ts +5 -0
  12. package/build/types/desktop/cmp/grid/editors/impl/InlineEditorModel.d.ts +6 -1
  13. package/build/types/desktop/cmp/input/NumberInput.d.ts +5 -2
  14. package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
  15. package/build/types/test-support/agGrid.d.ts +2 -0
  16. package/build/types/test-support/hoistCore.d.ts +7 -1
  17. package/build/types/test-support/index.d.ts +1 -0
  18. package/build/types/test-support/jsonBlobs.d.ts +130 -0
  19. package/build/types/test-support/testApp.d.ts +5 -2
  20. package/cmp/grid/Grid.ts +1 -1
  21. package/cmp/grid/GridModel.ts +8 -3
  22. package/cmp/grid/columns/Column.ts +1 -1
  23. package/cmp/input/impl/LiveCommas.ts +59 -0
  24. package/core/XH.ts +7 -6
  25. package/core/model/HoistModel.ts +4 -2
  26. package/core/model/Hooks.ts +1 -0
  27. package/core/model/ManagedRefreshContextModel.ts +5 -1
  28. package/data/README.md +3 -2
  29. package/data/cube/View.ts +3 -9
  30. package/data/cube/impl/RowCache.ts +2 -2
  31. package/data/cube/row/BaseRow.ts +14 -1
  32. package/data/cube/row/ParentRow.ts +1 -1
  33. package/desktop/cmp/dash/canvas/impl/DashCanvasView.ts +49 -52
  34. package/desktop/cmp/grid/editors/BooleanEditor.ts +2 -1
  35. package/desktop/cmp/grid/editors/DateEditor.ts +4 -1
  36. package/desktop/cmp/grid/editors/SelectEditor.ts +4 -1
  37. package/desktop/cmp/grid/editors/impl/InlineEditorModel.ts +17 -5
  38. package/desktop/cmp/input/NumberInput.ts +51 -12
  39. package/desktop/cmp/input/Select.ts +25 -7
  40. package/docs/README.md +2 -0
  41. package/docs/companion-library-docs.md +205 -0
  42. package/docs/doc-registry.json +8 -0
  43. package/docs/lifecycle-app.md +17 -0
  44. package/docs/unit-testing.md +54 -3
  45. package/docs/upgrade-notes/v89-upgrade-notes.md +101 -2
  46. package/docs/version-compatibility.md +2 -1
  47. package/icon/README.md +4 -1
  48. package/mcp/README.md +79 -4
  49. package/mcp/cli/docs.ts +75 -30
  50. package/mcp/data/doc-id-resolver.ts +50 -9
  51. package/mcp/data/doc-registry.ts +462 -44
  52. package/mcp/data/doc-search.ts +25 -6
  53. package/mcp/formatters/docs.ts +136 -36
  54. package/mcp/instructions.ts +69 -0
  55. package/mcp/resources/docs.ts +10 -8
  56. package/mcp/server.ts +7 -13
  57. package/mcp/tools/docs.ts +64 -18
  58. package/mcp/util/paths.ts +85 -2
  59. package/mobile/cmp/input/NumberInput.ts +42 -4
  60. package/package.json +19 -19
  61. package/public/msal-redirect-bridge.min.js +1 -1
  62. package/svc/JsonBlobService.ts +7 -4
  63. package/test-support/agGrid.ts +12 -2
  64. package/test-support/hoistCore.ts +32 -5
  65. package/test-support/index.ts +1 -0
  66. package/test-support/jsonBlobs.ts +543 -0
  67. package/test-support/setup.ts +16 -6
  68. package/test-support/testApp.ts +36 -7
@@ -7,6 +7,13 @@
7
7
  * it from a sibling checkout in local development or from a GitHub tarball in
8
8
  * production, then serves entries to the toolbox client).
9
9
  *
10
+ * Companion libraries - packages that build on Hoist, such as `@xh/hoist-chat-kit` or a client
11
+ * firm's own shared Hoist package - can add their docs to the same tools. A library opts in with
12
+ * `"hoist": {"docRegistry": "<path>"}` in its package.json, pointing at a registry file in the
13
+ * same JSON schema. {@link loadRegistry} finds opted-in packages among the direct dependencies of
14
+ * the consuming app (see `resolveAppRoot()` in `util/paths.ts`) and merges their entries in,
15
+ * with each id prefixed by the package name. See `docs/companion-library-docs.md`.
16
+ *
10
17
  * Hoist-core maintains a *separate* registry of server-side docs at its own
11
18
  * `docs/doc-registry.json`, consumed by its own (Groovy) MCP server. The two
12
19
  * registries use the same JSON schema, but the files and entries are
@@ -15,10 +22,18 @@
15
22
  * Provides metadata and file loading. Search lives in `doc-search.ts`, and the section model
16
23
  * used for search and targeted reads lives in `doc-sections.ts`.
17
24
  */
18
- import {existsSync, readFileSync} from 'node:fs';
25
+ import {existsSync, readFileSync, realpathSync} from 'node:fs';
26
+ import {isAbsolute, posix, relative, resolve, sep} from 'node:path';
19
27
 
20
28
  import {log} from '../util/logger.js';
21
- import {resolveDocPath} from '../util/paths.js';
29
+ import {
30
+ findInstalledPackage,
31
+ readPackageJson,
32
+ resolveAppRoot,
33
+ resolveDocPath,
34
+ resolveRepoRoot,
35
+ type PackageJson
36
+ } from '../util/paths.js';
22
37
 
23
38
  //------------------------------------------------------------------
24
39
  // Types
@@ -32,8 +47,16 @@ export interface McpCategory {
32
47
 
33
48
  /** A single document in the registry. */
34
49
  export interface DocEntry {
35
- /** Unique identifier AND relative file path (e.g. 'core/README.md', 'docs/lifecycle-app.md'). */
50
+ /**
51
+ * Unique identifier. For hoist-react docs, the file path relative to the repo root (e.g.
52
+ * 'core/README.md'). For companion library docs, that path prefixed with the package name
53
+ * (e.g. `@xh/hoist-chat-kit/core/README.md`).
54
+ */
36
55
  id: string;
56
+ /** File path relative to the owning package root, as declared in its registry. */
57
+ path: string;
58
+ /** Package name of the companion library that owns this doc, or null for hoist-react. */
59
+ library: string | null;
37
60
  /** Display title, e.g. 'Core Framework', 'Grid Component'. */
38
61
  title: string;
39
62
  /** Absolute file path on disk. */
@@ -48,83 +71,399 @@ export interface DocEntry {
48
71
  * Optional curated shortcut IDs accepted by the doc-id resolver. Use only
49
72
  * when the doc has an obvious short name that would otherwise be ambiguous
50
73
  * across multiple entries -- the resolver auto-generates safe shortenings
51
- * for unambiguous cases.
74
+ * for unambiguous cases. Declared unprefixed - the resolver scopes a
75
+ * companion library's aliases under its package name.
52
76
  */
53
77
  aliases: string[];
78
+ /** What a companion doc's relative links resolve against. See {@link rewriteRelativeLinks}. */
79
+ links?: DocLinkContext;
80
+ }
81
+
82
+ /** The docs and source location that a companion doc's relative links resolve against. */
83
+ export interface DocLinkContext {
84
+ /** Package name, the prefix of each doc id. */
85
+ library: string;
86
+ /** Registry paths of the library's served docs. */
87
+ docPaths: ReadonlySet<string>;
88
+ /** Where agents find the package files. See {@link DocLibrary.sourcePath}. */
89
+ sourcePath: string;
90
+ }
91
+
92
+ /** A package whose docs are loaded: hoist-react itself, or an opted-in companion library. */
93
+ export interface DocLibrary {
94
+ /** Package name, e.g. `@xh/hoist` or `@xh/hoist-chat-kit`. */
95
+ name: string;
96
+ version: string;
97
+ /** The package.json description, for the server instructions. */
98
+ description: string;
99
+ /** Absolute package root on disk, with symlinks resolved. */
100
+ root: string;
101
+ /**
102
+ * Where agents find the package files: relative to the working directory when inside it,
103
+ * else absolute. Under pnpm, the `node_modules` link rather than the store path.
104
+ */
105
+ sourcePath: string;
106
+ /** True for hoist-react, whose doc ids carry no prefix. */
107
+ primary: boolean;
108
+ /** Id of the library's `docs/README.md` index, if it registers one. */
109
+ indexId: string | null;
110
+ docCount: number;
111
+ /**
112
+ * Guidance for agents from the library's `mcpInstructions`, for example which Hoist
113
+ * components it replaces. The server instructions and ping surfaces show it. Always null for
114
+ * hoist-react, whose guidance is the server instructions themselves.
115
+ */
116
+ instructions: string | null;
117
+ }
118
+
119
+ /** Loaded registry data: entries, MCP category metadata, and the libraries they came from. */
120
+ export interface RegistryData {
121
+ entries: DocEntry[];
122
+ /** Union of categories across all libraries, hoist-react's first. */
123
+ mcpCategories: McpCategory[];
124
+ /** hoist-react first, then companion libraries in discovery order. */
125
+ libraries: DocLibrary[];
126
+ /** Companion library load problems - also logged, and reported by the ping surfaces. */
127
+ warnings: string[];
54
128
  }
55
129
 
56
130
  //------------------------------------------------------------------
57
131
  // JSON loading
58
132
  //------------------------------------------------------------------
59
133
 
60
- /** Raw JSON structure of docs/doc-registry.json. */
134
+ /**
135
+ * Raw JSON structure of a doc registry file. Only `entries[].id` is required, so a companion
136
+ * library can start with a minimal file. hoist-react's own registry fills in every field.
137
+ */
61
138
  interface RegistryJson {
62
- mcpCategories: McpCategory[];
63
- viewerCategories: Array<{id: string; title: string}>;
64
- entries: Array<{
139
+ mcpCategories?: McpCategory[];
140
+ /** Guidance for agents from a companion library. A string, or an array of lines. */
141
+ mcpInstructions?: string | string[];
142
+ viewerCategories?: Array<{id: string; title: string}>;
143
+ entries?: Array<{
65
144
  id: string;
66
- title: string;
67
- mcpCategory: string;
68
- viewerCategory: string;
69
- description: string;
70
- keywords: string[];
145
+ title?: string;
146
+ mcpCategory?: string;
147
+ viewerCategory?: string;
148
+ description?: string;
149
+ keywords?: string[];
71
150
  aliases?: string[];
151
+ /** `maintainers` to serve the doc only to agents working in the library's own repo. */
152
+ mcpAudience?: string;
72
153
  }>;
73
154
  }
74
155
 
75
- /** Loaded registry data: entries + MCP category metadata. */
76
- export interface RegistryData {
77
- entries: DocEntry[];
78
- mcpCategories: McpCategory[];
79
- }
80
-
81
- /** Load and parse docs/doc-registry.json from the repo root. */
82
- function loadRegistryJson(repoRoot: string): RegistryJson {
83
- const jsonPath = resolveDocPath(repoRoot, 'docs/doc-registry.json');
156
+ /** Load and parse a registry file, or return null (and warn) if missing or invalid. */
157
+ function loadRegistryJson(jsonPath: string, warn: (msg: string) => void): RegistryJson | null {
84
158
  if (!existsSync(jsonPath)) {
85
- log.warn('docs/doc-registry.json not found');
86
- return {mcpCategories: [], viewerCategories: [], entries: []};
159
+ warn(`doc registry not found at ${jsonPath}`);
160
+ return null;
161
+ }
162
+ try {
163
+ return JSON.parse(readFileSync(jsonPath, 'utf-8'));
164
+ } catch (e) {
165
+ warn(`doc registry at ${jsonPath} is not valid JSON: ${e}`);
166
+ return null;
87
167
  }
88
- return JSON.parse(readFileSync(jsonPath, 'utf-8'));
89
168
  }
90
169
 
91
170
  //------------------------------------------------------------------
92
171
  // Registry builder
93
172
  //------------------------------------------------------------------
94
173
 
174
+ /** Package name of hoist-react, which owns the primary docs. */
175
+ export const HOIST_PACKAGE = '@xh/hoist';
176
+
95
177
  /**
96
- * Build the complete document registry from docs/doc-registry.json.
178
+ * Build the complete document registry: hoist-react's docs, plus those of any companion
179
+ * libraries discovered from `appRoot`. Omit `appRoot` to load hoist-react's docs alone.
97
180
  *
98
181
  * Each entry's file path is validated at build time; missing files are
99
182
  * logged and skipped.
100
183
  */
101
- export function buildRegistry(repoRoot: string): RegistryData {
102
- const json = loadRegistryJson(repoRoot);
103
- const entries: DocEntry[] = [];
184
+ export function buildRegistry(
185
+ repoRoot: string,
186
+ {appRoot}: {appRoot?: string | null} = {}
187
+ ): RegistryData {
188
+ const warnings: string[] = [],
189
+ hoistPkg = readPackageJson(repoRoot),
190
+ isAppRoot = (root: string) => appRoot != null && samePath(root, appRoot),
191
+ primary = loadLibrary(
192
+ repoRoot,
193
+ hoistPkg ?? {name: HOIST_PACKAGE},
194
+ 'docs/doc-registry.json',
195
+ {primary: true, isAppRoot: isAppRoot(repoRoot), sourcePath: displayPath(repoRoot)},
196
+ msg => log.warn(msg)
197
+ )!;
198
+
199
+ const libraries = [primary.library],
200
+ entries = [...primary.entries],
201
+ mcpCategories = [...primary.mcpCategories];
202
+
203
+ for (const {path, pkg} of appRoot ? discoverCompanionPackages(appRoot) : []) {
204
+ const name = pkg.name!,
205
+ warn = (msg: string) => {
206
+ warnings.push(`${name}: ${msg}`);
207
+ log.warn(`Companion library ${name}: ${msg}`);
208
+ },
209
+ loaded = loadCompanion(path, pkg, isAppRoot(path), warn);
210
+ if (!loaded) continue;
211
+
212
+ // An unscoped package named like a hoist-react folder (e.g. `core`) could produce an id
213
+ // that is already taken. Ids must be unique, so the first claimant keeps it.
214
+ const taken = new Set(entries.map(e => e.id)),
215
+ kept = loaded.entries.filter(e => {
216
+ if (!taken.has(e.id)) return true;
217
+ warn(`skipped "${e.path}": id "${e.id}" is already registered`);
218
+ return false;
219
+ });
220
+
221
+ const links: DocLinkContext = {
222
+ library: name,
223
+ docPaths: new Set(kept.map(e => e.path)),
224
+ sourcePath: loaded.library.sourcePath
225
+ };
226
+ libraries.push({...loaded.library, docCount: kept.length});
227
+ entries.push(...kept.map(e => ({...e, links})));
228
+ for (const cat of loaded.mcpCategories) {
229
+ if (!mcpCategories.some(c => c.id === cat.id)) mcpCategories.push(cat);
230
+ }
231
+ }
232
+
233
+ const companions = libraries.length - 1;
234
+ log.info(
235
+ `Document registry built: ${entries.length} entries across ${new Set(entries.map(e => e.mcpCategory)).size} categories` +
236
+ (companions
237
+ ? `, including ${companions} companion librar${companions > 1 ? 'ies' : 'y'}`
238
+ : '')
239
+ );
240
+ return {entries, mcpCategories, libraries, warnings};
241
+ }
242
+
243
+ /**
244
+ * Load a companion library, or return null. A library's files must never stop Hoist's own docs
245
+ * from loading, so any error it causes becomes a warning.
246
+ */
247
+ function loadCompanion(
248
+ path: string,
249
+ pkg: PackageJson,
250
+ isAppRoot: boolean,
251
+ warn: (msg: string) => void
252
+ ): ReturnType<typeof loadLibrary> {
253
+ try {
254
+ return loadLibrary(
255
+ realpathSync(path),
256
+ pkg,
257
+ pkg.hoist!.docRegistry!,
258
+ {primary: false, isAppRoot, sourcePath: displayPath(path)},
259
+ warn
260
+ );
261
+ } catch (e) {
262
+ warn(`failed to load: ${(e as Error).message}`);
263
+ return null;
264
+ }
265
+ }
266
+
267
+ /** `path` relative to the working directory when inside it, else absolute. */
268
+ function displayPath(path: string): string {
269
+ const rel = relative(process.cwd(), path);
270
+ if (!rel) return '.';
271
+ return rel.startsWith('..') || isAbsolute(rel) ? path : rel;
272
+ }
273
+
274
+ /** True if two paths name the same folder, following symlinks. */
275
+ function samePath(a: string, b: string): boolean {
276
+ try {
277
+ return realpathSync(a) === realpathSync(b);
278
+ } catch {
279
+ return resolve(a) === resolve(b);
280
+ }
281
+ }
282
+
283
+ /**
284
+ * Load one library's registry, resolving each entry against the library's own root. Returns
285
+ * null for a companion library whose registry cannot be read. hoist-react's own registry always
286
+ * loads, if only as an empty one.
287
+ *
288
+ * Entries with `mcpAudience: 'maintainers'` load only when the library is the app root - that
289
+ * is, when an agent works in the library's own repo.
290
+ */
291
+ function loadLibrary(
292
+ root: string,
293
+ pkg: PackageJson,
294
+ registryPath: string,
295
+ {primary, isAppRoot, sourcePath}: {primary: boolean; isAppRoot: boolean; sourcePath: string},
296
+ warn: (msg: string) => void
297
+ ): {library: DocLibrary; entries: DocEntry[]; mcpCategories: McpCategory[]} | null {
298
+ const name = pkg.name ?? HOIST_PACKAGE;
299
+ let json: RegistryJson | null = null;
300
+ try {
301
+ json = loadRegistryJson(resolveDocPath(root, registryPath), warn);
302
+ } catch (e) {
303
+ warn(`invalid docRegistry path "${registryPath}": ${(e as Error).message}`);
304
+ }
305
+ if (!json) {
306
+ if (!primary) return null;
307
+ json = {};
308
+ }
104
309
 
105
- for (const raw of json.entries) {
106
- const filePath = resolveDocPath(repoRoot, raw.id);
310
+ const entries: DocEntry[] = [],
311
+ realRoot = realpathSync(root);
312
+ for (const raw of arrayField(json.entries, 'entries', warn)) {
313
+ if (typeof raw?.id !== 'string' || !raw.id) {
314
+ warn('skipped an entry with no id');
315
+ continue;
316
+ }
317
+ if (raw.mcpAudience != null && raw.mcpAudience !== 'maintainers') {
318
+ warn(`ignored mcpAudience "${raw.mcpAudience}" on "${raw.id}": expected "maintainers"`);
319
+ }
320
+ if (raw.mcpAudience === 'maintainers' && !isAppRoot) continue;
107
321
 
322
+ let filePath: string;
323
+ try {
324
+ filePath = resolveDocPath(root, raw.id);
325
+ } catch (e) {
326
+ warn(`skipped "${raw.id}": ${(e as Error).message}`);
327
+ continue;
328
+ }
108
329
  if (!existsSync(filePath)) {
109
- log.warn(`Skipping doc entry "${raw.id}": file not found at ${filePath}`);
330
+ warn(`skipped doc entry "${raw.id}": file not found at ${filePath}`);
331
+ continue;
332
+ }
333
+ if (!realpathSync(filePath).startsWith(realRoot + sep)) {
334
+ warn(`skipped "${raw.id}": it links to a file outside the package root`);
110
335
  continue;
111
336
  }
112
337
 
113
338
  entries.push({
114
- id: raw.id,
115
- title: raw.title,
339
+ id: primary ? raw.id : `${name}/${raw.id}`,
340
+ path: raw.id,
341
+ library: primary ? null : name,
342
+ title: stringField(raw.title, raw.id),
116
343
  filePath,
117
- mcpCategory: raw.mcpCategory,
118
- description: raw.description,
119
- keywords: raw.keywords ?? [],
120
- aliases: raw.aliases ?? []
344
+ mcpCategory: stringField(raw.mcpCategory, 'package'),
345
+ description: stringField(raw.description, ''),
346
+ keywords: stringsField(raw.keywords),
347
+ aliases: stringsField(raw.aliases)
121
348
  });
122
349
  }
123
350
 
124
- log.info(
125
- `Document registry built: ${entries.length} entries across ${new Set(entries.map(e => e.mcpCategory)).size} categories`
126
- );
127
- return {entries, mcpCategories: json.mcpCategories ?? []};
351
+ // Categories the registry declares, then any an entry uses without declaring.
352
+ const mcpCategories = arrayField(json.mcpCategories, 'mcpCategories', warn)
353
+ .filter(c => typeof c?.id === 'string' && c.id)
354
+ .map(c => ({id: c.id, title: stringField(c.title, c.id)}));
355
+ for (const id of new Set(entries.map(e => e.mcpCategory))) {
356
+ if (!mcpCategories.some(c => c.id === id)) {
357
+ mcpCategories.push({id, title: id.charAt(0).toUpperCase() + id.slice(1)});
358
+ }
359
+ }
360
+
361
+ const index = entries.find(e => e.path === 'docs/README.md');
362
+ return {
363
+ library: {
364
+ name,
365
+ version: stringField(pkg.version, 'unknown'),
366
+ description: stringField(pkg.description, ''),
367
+ root,
368
+ sourcePath,
369
+ primary,
370
+ indexId: index?.id ?? null,
371
+ docCount: entries.length,
372
+ instructions: primary ? null : parseInstructions(json.mcpInstructions, warn)
373
+ },
374
+ entries,
375
+ mcpCategories
376
+ };
377
+ }
378
+
379
+ /*
380
+ * Field readers for registry and package.json values. Companion files come from any dependency,
381
+ * so a field of the wrong type falls back to its default rather than throwing later.
382
+ */
383
+ function stringField(value: unknown, fallback: string): string {
384
+ return typeof value === 'string' ? value : fallback;
385
+ }
386
+
387
+ function stringsField(value: unknown): string[] {
388
+ return Array.isArray(value) ? value.filter(it => typeof it === 'string') : [];
389
+ }
390
+
391
+ function arrayField<T>(value: T[] | undefined, field: string, warn: (msg: string) => void): T[] {
392
+ if (value == null) return [];
393
+ if (Array.isArray(value)) return value;
394
+ warn(`ignored ${field}: expected an array`);
395
+ return [];
396
+ }
397
+
398
+ /** Longest library guidance accepted, in characters. Longer guidance is cut, with a warning. */
399
+ export const MAX_LIBRARY_INSTRUCTIONS_CHARS = 1500;
400
+
401
+ /** Normalize `mcpInstructions` to trimmed, non-empty lines, or null if absent or invalid. */
402
+ function parseInstructions(
403
+ raw: RegistryJson['mcpInstructions'],
404
+ warn: (msg: string) => void
405
+ ): string | null {
406
+ if (raw == null) return null;
407
+ const valid =
408
+ typeof raw === 'string' || (Array.isArray(raw) && raw.every(it => typeof it === 'string'));
409
+ if (!valid) {
410
+ warn('ignored mcpInstructions: expected a string or an array of strings');
411
+ return null;
412
+ }
413
+
414
+ const text = [raw]
415
+ .flat()
416
+ .join('\n')
417
+ .split('\n')
418
+ .map(line => line.trim())
419
+ .filter(Boolean)
420
+ .join('\n');
421
+ if (text.length <= MAX_LIBRARY_INSTRUCTIONS_CHARS) return text || null;
422
+
423
+ warn(`mcpInstructions cut to ${MAX_LIBRARY_INSTRUCTIONS_CHARS} of ${text.length} characters`);
424
+ return text.slice(0, MAX_LIBRARY_INSTRUCTIONS_CHARS - 3) + '...';
425
+ }
426
+
427
+ /**
428
+ * Find opted-in companion packages: the app package itself, then its direct `dependencies` and
429
+ * `devDependencies`. Transitive dependencies are not walked. `@xh/hoist` is skipped - its docs
430
+ * are always loaded as the primary library.
431
+ */
432
+ function discoverCompanionPackages(appRoot: string): Array<{path: string; pkg: PackageJson}> {
433
+ const appPkg = readPackageJson(appRoot);
434
+ if (!appPkg) return [];
435
+
436
+ const candidates: Array<{path: string; pkg: PackageJson}> = [{path: appRoot, pkg: appPkg}],
437
+ depNames = new Set([
438
+ ...Object.keys(appPkg.dependencies ?? {}),
439
+ ...Object.keys(appPkg.devDependencies ?? {})
440
+ ]);
441
+ for (const depName of depNames) {
442
+ const path = findInstalledPackage(appRoot, depName),
443
+ pkg = path ? readPackageJson(path) : null;
444
+ if (path && pkg) candidates.push({path, pkg});
445
+ }
446
+
447
+ const seen = new Set<string>();
448
+ return candidates.filter(({pkg}) => {
449
+ if (typeof pkg.name !== 'string' || !pkg.name) return false;
450
+ if (pkg.name === HOIST_PACKAGE || seen.has(pkg.name)) return false;
451
+ if (typeof pkg.hoist?.docRegistry !== 'string') return false;
452
+ seen.add(pkg.name);
453
+ return true;
454
+ });
455
+ }
456
+
457
+ /** Memoized registry shared by the MCP tools, resources, and server instructions. */
458
+ let cachedRegistry: RegistryData | undefined;
459
+
460
+ /**
461
+ * Load the registry for this process: hoist-react's docs plus companion libraries discovered
462
+ * from the consuming app. Built once and shared by every surface.
463
+ */
464
+ export function loadRegistry(): RegistryData {
465
+ cachedRegistry ??= buildRegistry(resolveRepoRoot(), {appRoot: resolveAppRoot()});
466
+ return cachedRegistry;
128
467
  }
129
468
 
130
469
  //------------------------------------------------------------------
@@ -132,7 +471,8 @@ export function buildRegistry(repoRoot: string): RegistryData {
132
471
  //------------------------------------------------------------------
133
472
 
134
473
  /**
135
- * Read and return the full content of a document.
474
+ * Read and return the full content of a document. A companion library doc has its relative links
475
+ * rewritten to full ids - see {@link rewriteRelativeLinks}.
136
476
  *
137
477
  * @throws Error if the file does not exist.
138
478
  */
@@ -140,5 +480,83 @@ export function loadDocContent(entry: DocEntry): string {
140
480
  if (!existsSync(entry.filePath)) {
141
481
  throw new Error(`Document file not found: "${entry.id}" at ${entry.filePath}`);
142
482
  }
143
- return readFileSync(entry.filePath, 'utf-8');
483
+ const content = readFileSync(entry.filePath, 'utf-8');
484
+ return entry.links ? rewriteRelativeLinks(content, entry.path, entry.links) : content;
485
+ }
486
+
487
+ /** Inline link or image `](target`, capturing the lead and the target. */
488
+ const INLINE_LINK_RE = /(\]\(\s*<?)([^\s)>]+)/g;
489
+
490
+ /**
491
+ * A whole line that is a link reference definition, `[label]: target` with an optional title.
492
+ * Captures the lead, the target, and the rest. Excludes footnotes (`[^1]: text`) and prose such as
493
+ * `[Note]: remember this`, whose text after the target is not a title.
494
+ */
495
+ const REF_DEF_RE =
496
+ /^(\s{0,3}\[(?!\^)[^\]]+\]:\s*<?)([^\s>]+)(>?(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*)$/;
497
+
498
+ /**
499
+ * Fence that opens or closes a markdown code block. Any indent, so a fence nested in a list
500
+ * item counts too.
501
+ */
502
+ const FENCE_RE = /^\s*(`{3,}|~{3,})/;
503
+
504
+ /**
505
+ * Rewrite relative links in a companion library doc so an agent can follow them. Read as
506
+ * written, `../core/README.md` in `@xh/hoist-chat-kit/docs/architecture.md` sends an agent to
507
+ * hoist-react's `core/README.md`, with no error to tell it the doc is the wrong one.
508
+ *
509
+ * A link to a served doc becomes its full id, prefixed with the package name. A link to any other
510
+ * file in the package, such as source or a doc not served here, becomes a file path under
511
+ * {@link DocLinkContext.sourcePath}. Leaves anchors, absolute paths, URLs, links that leave the
512
+ * package root, and code as they are. Keeps line numbers unchanged, so section line ranges still
513
+ * match the file.
514
+ */
515
+ export function rewriteRelativeLinks(
516
+ content: string,
517
+ docPath: string,
518
+ {library, docPaths, sourcePath}: DocLinkContext
519
+ ): string {
520
+ const docDir = posix.dirname(docPath);
521
+ // The open fence, if inside a code block. It closes on a fence of the same character, at
522
+ // least as long.
523
+ let openFence: string | null = null;
524
+ return content
525
+ .split('\n')
526
+ .map(line => {
527
+ const fence = FENCE_RE.exec(line)?.[1];
528
+ if (fence) {
529
+ if (!openFence) {
530
+ openFence = fence;
531
+ } else if (fence[0] === openFence[0] && fence.length >= openFence.length) {
532
+ openFence = null;
533
+ }
534
+ return line;
535
+ }
536
+ if (openFence) return line;
537
+ const def = REF_DEF_RE.exec(line);
538
+ if (def) return def[1] + rewrite(def[2]) + def[3];
539
+ // Odd segments are inline code spans, left as written.
540
+ return line
541
+ .split(/(`+[^`]*`+)/)
542
+ .map((seg, i) =>
543
+ i % 2 ? seg : seg.replace(INLINE_LINK_RE, (_, lead, t) => lead + rewrite(t))
544
+ )
545
+ .join('');
546
+ })
547
+ .join('\n');
548
+
549
+ function rewrite(target: string): string {
550
+ if (/^([a-z][a-z0-9+.-]*:|[#/])/i.test(target)) return target;
551
+ const hashAt = target.indexOf('#'),
552
+ path = hashAt < 0 ? target : target.slice(0, hashAt),
553
+ anchor = hashAt < 0 ? '' : target.slice(hashAt),
554
+ resolved = posix.normalize(posix.join(docDir, path));
555
+ if (resolved === '..' || resolved.startsWith('../')) return target;
556
+ if (resolved === '.') return library + anchor;
557
+ const rewritten = docPaths.has(resolved)
558
+ ? `${library}/${resolved}`
559
+ : posix.join(sourcePath.split(sep).join('/'), resolved);
560
+ return rewritten + anchor;
561
+ }
144
562
  }
@@ -1,5 +1,6 @@
1
1
  /**
2
- * Section-level ranked search over hoist-react documentation.
2
+ * Section-level ranked search over hoist-react documentation, plus any companion library docs in
3
+ * the registry. All libraries share one index.
3
4
  *
4
5
  * Every registered doc is split into sections (see `doc-sections.ts`) and indexed with
5
6
  * MiniSearch (BM25+). Each section is indexed on two fields: its heading breadcrumb
@@ -16,7 +17,7 @@
16
17
  import MiniSearch, {type SearchOptions, type SearchResult} from 'minisearch';
17
18
 
18
19
  import {log} from '../util/logger.js';
19
- import {loadDocContent, type DocEntry} from './doc-registry.js';
20
+ import {HOIST_PACKAGE, loadDocContent, type DocEntry} from './doc-registry.js';
20
21
  import {LINK_DEF_RE, parseDocSections, stripLinks, type DocSection} from './doc-sections.js';
21
22
  import {
22
23
  createTermProcessor,
@@ -44,6 +45,8 @@ export interface DocSearchResult {
44
45
  export interface DocSearchOptions {
45
46
  /** MCP category ID to filter by, or `all`. */
46
47
  category?: string;
48
+ /** Library to filter by - a package name, `@xh/hoist` for hoist-react's own docs. */
49
+ library?: string;
47
50
  /** Maximum results. Clamped to 1-{@link MAX_SEARCH_LIMIT}. */
48
51
  limit?: number;
49
52
  }
@@ -72,7 +75,8 @@ const DOC_META_BOOST = 1.3;
72
75
  * rarely the best answer to a how-to query, so they rank below the primary docs.
73
76
  */
74
77
  function docWeight(entry: DocEntry): number {
75
- if (entry.id.startsWith('docs/upgrade-notes/')) return 0.5;
78
+ // Checks the registry path, so a companion library's upgrade notes rank the same way.
79
+ if (entry.path.startsWith('docs/upgrade-notes/')) return 0.5;
76
80
  // The MCP server's own README documents this tooling, not app development. It mentions many
77
81
  // framework terms in passing and otherwise outranks the docs that answer the question.
78
82
  if (entry.id === 'mcp/README.md') return 0.5;
@@ -101,6 +105,7 @@ export function searchDocs(
101
105
  const idx = getSearchIndex(registry),
102
106
  limit = Math.min(Math.max(options.limit ?? DEFAULT_SEARCH_LIMIT, 1), MAX_SEARCH_LIMIT),
103
107
  category = options.category && options.category !== 'all' ? options.category : null,
108
+ library = options.library ?? null,
104
109
  querySet = new Set(terms),
105
110
  searchOpts: SearchOptions = {
106
111
  boost: FIELD_BOOST,
@@ -116,7 +121,16 @@ export function searchDocs(
116
121
  meta = idx.metaTerms.get(section.docId);
117
122
  return idx.weights.get(section.docId)! * (meta?.has(term) ? DOC_META_BOOST : 1);
118
123
  },
119
- filter: category ? hit => idx.sections[hit.id].category === category : undefined
124
+ filter:
125
+ category || library
126
+ ? hit => {
127
+ const it = idx.sections[hit.id];
128
+ return (
129
+ (!category || it.category === category) &&
130
+ (!library || it.library === library)
131
+ );
132
+ }
133
+ : undefined
120
134
  },
121
135
  q = terms.join(' ');
122
136
 
@@ -161,7 +175,7 @@ interface IndexedSection {
161
175
  interface SearchIndex {
162
176
  miniSearch: MiniSearch<IndexedSection>;
163
177
  /** Indexed sections by MiniSearch document id. */
164
- sections: Array<{section: DocSection; category: string; docId: string}>;
178
+ sections: Array<{section: DocSection; category: string; library: string; docId: string}>;
165
179
  entries: Map<string, DocEntry>;
166
180
  /** Processed terms from each doc's registry title, description, and keywords. */
167
181
  metaTerms: Map<string, Set<string>>;
@@ -213,7 +227,12 @@ function getSearchIndex(registry: DocEntry[]): SearchIndex {
213
227
  if (body.replace(/[^\p{L}\p{N}]/gu, '').length < 20) continue;
214
228
 
215
229
  const id = sections.length;
216
- sections.push({section, category: entry.mcpCategory, docId: entry.id});
230
+ sections.push({
231
+ section,
232
+ category: entry.mcpCategory,
233
+ library: entry.library ?? HOIST_PACKAGE,
234
+ docId: entry.id
235
+ });
217
236
  docs.push({id, heading: [section.breadcrumb, ...subHeadings(body)].join(' '), body});
218
237
  }
219
238
  }