@xh/hoist 89.0.1 → 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.
- package/CHANGELOG.md +36 -0
- package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
- package/build/types/core/model/HoistModel.d.ts +1 -0
- package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
- package/build/types/data/cube/View.d.ts +0 -2
- package/build/types/data/cube/impl/RowCache.d.ts +1 -1
- package/build/types/data/cube/row/BaseRow.d.ts +5 -0
- package/build/types/desktop/cmp/grid/editors/impl/InlineEditorModel.d.ts +6 -1
- package/build/types/desktop/cmp/input/NumberInput.d.ts +5 -2
- package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
- package/build/types/test-support/agGrid.d.ts +2 -0
- package/build/types/test-support/hoistCore.d.ts +7 -1
- package/build/types/test-support/index.d.ts +1 -0
- package/build/types/test-support/jsonBlobs.d.ts +130 -0
- package/build/types/test-support/testApp.d.ts +5 -2
- package/cmp/grid/columns/Column.ts +1 -1
- package/cmp/input/impl/LiveCommas.ts +59 -0
- package/core/model/HoistModel.ts +4 -2
- package/core/model/Hooks.ts +1 -0
- package/core/model/ManagedRefreshContextModel.ts +5 -1
- package/data/cube/View.ts +3 -9
- package/data/cube/impl/RowCache.ts +2 -2
- package/data/cube/row/BaseRow.ts +14 -1
- package/data/cube/row/ParentRow.ts +1 -1
- package/desktop/cmp/grid/editors/BooleanEditor.ts +2 -1
- package/desktop/cmp/grid/editors/DateEditor.ts +4 -1
- package/desktop/cmp/grid/editors/SelectEditor.ts +4 -1
- package/desktop/cmp/grid/editors/impl/InlineEditorModel.ts +17 -5
- package/desktop/cmp/input/NumberInput.ts +51 -12
- package/desktop/cmp/input/Select.ts +25 -7
- package/docs/README.md +2 -0
- package/docs/companion-library-docs.md +205 -0
- package/docs/doc-registry.json +8 -0
- package/docs/lifecycle-app.md +17 -0
- package/docs/unit-testing.md +54 -3
- package/docs/upgrade-notes/v89-upgrade-notes.md +7 -1
- package/docs/version-compatibility.md +2 -1
- package/icon/README.md +4 -1
- package/mcp/README.md +79 -4
- package/mcp/cli/docs.ts +75 -30
- package/mcp/data/doc-id-resolver.ts +50 -9
- package/mcp/data/doc-registry.ts +462 -44
- package/mcp/data/doc-search.ts +25 -6
- package/mcp/formatters/docs.ts +136 -36
- package/mcp/instructions.ts +69 -0
- package/mcp/resources/docs.ts +10 -8
- package/mcp/server.ts +7 -13
- package/mcp/tools/docs.ts +64 -18
- package/mcp/util/paths.ts +85 -2
- package/mobile/cmp/input/NumberInput.ts +42 -4
- package/package.json +19 -19
- package/public/msal-redirect-bridge.min.js +1 -1
- package/svc/JsonBlobService.ts +7 -4
- package/test-support/agGrid.ts +12 -2
- package/test-support/hoistCore.ts +32 -5
- package/test-support/index.ts +1 -0
- package/test-support/jsonBlobs.ts +543 -0
- package/test-support/setup.ts +8 -6
- package/test-support/testApp.ts +36 -7
package/mcp/data/doc-registry.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
63
|
-
|
|
64
|
-
|
|
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
|
|
67
|
-
mcpCategory
|
|
68
|
-
viewerCategory
|
|
69
|
-
description
|
|
70
|
-
keywords
|
|
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
|
-
/**
|
|
76
|
-
|
|
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
|
-
|
|
86
|
-
return
|
|
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
|
|
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(
|
|
102
|
-
|
|
103
|
-
|
|
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
|
-
|
|
106
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
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
|
}
|
package/mcp/data/doc-search.ts
CHANGED
|
@@ -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
|
-
|
|
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:
|
|
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({
|
|
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
|
}
|