@xh/hoist 89.0.1 → 89.2.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 +75 -0
- package/build/types/cmp/grid/GridModel.d.ts +6 -0
- package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
- package/build/types/cmp/viewmanager/ViewManagerModel.d.ts +4 -2
- package/build/types/core/XH.d.ts +2 -1
- package/build/types/core/model/HoistModel.d.ts +1 -0
- package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
- package/build/types/core/persist/PersistenceProvider.d.ts +3 -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/dash/DashViewSpec.d.ts +2 -1
- package/build/types/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.d.ts +1 -1
- package/build/types/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.d.ts +3 -2
- package/build/types/desktop/cmp/dash/container/impl/DashContainerContextMenu.d.ts +1 -1
- package/build/types/desktop/cmp/dash/impl/DashUtils.d.ts +35 -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/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.d.ts +1 -2
- package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
- package/build/types/svc/FetchService.d.ts +19 -0
- 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/Grid.ts +2 -2
- package/cmp/grid/GridModel.ts +14 -1
- package/cmp/grid/columns/Column.ts +3 -2
- package/cmp/input/impl/LiveCommas.ts +59 -0
- package/cmp/viewmanager/ViewManagerModel.ts +25 -7
- package/core/XH.ts +8 -3
- package/core/model/HoistModel.ts +4 -2
- package/core/model/Hooks.ts +1 -0
- package/core/model/ManagedRefreshContextModel.ts +5 -1
- package/core/persist/PersistenceProvider.ts +15 -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/dash/DashViewSpec.ts +2 -1
- package/desktop/cmp/dash/README.md +6 -5
- package/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.ts +1 -1
- package/desktop/cmp/dash/canvas/impl/utils.ts +16 -51
- package/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.ts +37 -54
- package/desktop/cmp/dash/container/impl/DashContainerContextMenu.ts +8 -39
- package/desktop/cmp/dash/impl/DashUtils.ts +90 -0
- 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/desktop/cmp/tab/TabSwitcher.ts +4 -6
- package/desktop/cmp/tab/dynamic/DynamicTabSwitcher.ts +4 -5
- package/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.ts +2 -7
- package/docs/README.md +2 -0
- package/docs/build-and-publish.md +21 -11
- package/docs/companion-library-docs.md +205 -0
- package/docs/doc-registry.json +9 -1
- package/docs/lifecycle-app.md +17 -0
- package/docs/lifecycle-models-and-services.md +2 -1
- package/docs/persistence.md +2 -0
- package/docs/telemetry.md +29 -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/FetchService.ts +38 -2
- package/svc/JsonBlobService.ts +7 -4
- package/svc/README.md +7 -3
- 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/build/types/desktop/cmp/tab/impl/TabContextMenuItems.d.ts +0 -4
- package/desktop/cmp/tab/impl/TabContextMenuItems.ts +0 -23
package/mcp/README.md
CHANGED
|
@@ -25,7 +25,8 @@ Both interfaces share the same underlying registries and produce identical outpu
|
|
|
25
25
|
**What they provide:**
|
|
26
26
|
|
|
27
27
|
- **Documentation tools** - search and browse all hoist-react READMEs, concept docs, and upgrade
|
|
28
|
-
notes
|
|
28
|
+
notes. They also serve the docs of [companion libraries](#companion-library-docs) that the app
|
|
29
|
+
installs
|
|
29
30
|
- **TypeScript tools** - search symbols, inspect types, and list class/interface members
|
|
30
31
|
- **Documentation resources** - direct access to any doc by `hoist://docs/{id}` URI. Resources are
|
|
31
32
|
an MCP mechanism with no CLI counterpart, but the capability is on both surfaces:
|
|
@@ -48,12 +49,14 @@ AI-authored component in hoist-react.
|
|
|
48
49
|
```
|
|
49
50
|
mcp/
|
|
50
51
|
├── server.ts # MCP entry point - creates McpServer, registers all capabilities
|
|
52
|
+
├── instructions.ts # Server instructions, built from the loaded doc registry
|
|
51
53
|
├── cli/
|
|
52
54
|
│ ├── docs.ts # CLI entry point for hoist-docs
|
|
53
55
|
│ ├── ts.ts # CLI entry point for hoist-ts
|
|
54
56
|
│ └── ts-command.ts # hoist-ts command with injectable io (specs run it in-process)
|
|
55
57
|
├── data/
|
|
56
|
-
│ ├── doc-registry.ts #
|
|
58
|
+
│ ├── doc-registry.ts # Doc inventory loader: docs/doc-registry.json plus companion libraries
|
|
59
|
+
│ ├── companion-docs.spec.ts # Companion library discovery, id scoping, and surfaces (see Testing)
|
|
57
60
|
│ ├── doc-id-resolver.ts # Tolerant doc-id resolver (canonical + shortenings + aliases)
|
|
58
61
|
│ ├── doc-id-resolver.spec.ts # Resolver test cases (see Testing)
|
|
59
62
|
│ ├── doc-sections.ts # Splits docs into ##/### sections; section-name resolution
|
|
@@ -79,7 +82,7 @@ mcp/
|
|
|
79
82
|
│ └── typescript.spec.ts # MCP / CLI parity check for the TypeScript tools
|
|
80
83
|
├── util/
|
|
81
84
|
│ ├── logger.ts # Stderr-only logging (protects stdio JSON-RPC)
|
|
82
|
-
│ └── paths.ts # Repo root resolution
|
|
85
|
+
│ └── paths.ts # Repo and app root resolution, package lookup, path traversal safety
|
|
83
86
|
├── eslint.config.mjs # ESLint config for mcp/ (run by pnpm lint:mcp)
|
|
84
87
|
├── package.json # ES module config (type: "module")
|
|
85
88
|
├── README.md # This document
|
|
@@ -320,6 +323,63 @@ calls is the most common bug in MCP server implementations. The custom logger in
|
|
|
320
323
|
writes exclusively to stderr. The CLI uses `process.stdout.write()` for output and `console.error()`
|
|
321
324
|
for errors.
|
|
322
325
|
|
|
326
|
+
### Companion Library Docs
|
|
327
|
+
|
|
328
|
+
Libraries that build on Hoist can serve their docs through these tools. Examples are
|
|
329
|
+
`@xh/hoist-chat-kit` and a client firm's package of Hoist overrides. A library opts in with
|
|
330
|
+
`"hoist": {"docRegistry": "<path>"}` in its `package.json`. The author guide is
|
|
331
|
+
[Companion Library Docs](../docs/companion-library-docs.md). This section covers the
|
|
332
|
+
implementation.
|
|
333
|
+
|
|
334
|
+
- **One shared registry.** `loadRegistry()` in `data/doc-registry.ts` builds the registry once per
|
|
335
|
+
process. The tools, resources, CLI, and server instructions all use it. Specs pass a registry
|
|
336
|
+
built from a fixture to `registerDocTools()` and `registerDocResources()`.
|
|
337
|
+
- **Discovery starts from the app.** Under pnpm, `@xh/hoist` resolves into the `.pnpm` store. It
|
|
338
|
+
does not depend on the companion library, so the server cannot find it from its own location.
|
|
339
|
+
`resolveAppRoot()` in `util/paths.ts` picks the anchor package: `HOIST_MCP_APP_ROOT`, else the
|
|
340
|
+
nearest package that uses Hoist among `cwd`, `cwd/client-app`, and the same pair in each parent
|
|
341
|
+
folder. The loader checks the anchor and its direct `dependencies` and `devDependencies`.
|
|
342
|
+
`findInstalledPackage()` finds each one under `node_modules`. It does not use
|
|
343
|
+
`require.resolve()`, which fails for packages with an `exports` map. The loader resolves docs
|
|
344
|
+
against the real path, and shows agents the `node_modules` path as `DocLibrary.sourcePath`,
|
|
345
|
+
relative to the working directory.
|
|
346
|
+
- **Prefixed ids.** Companion ids are the package name plus the registry path, for example
|
|
347
|
+
`@xh/hoist-chat-kit/core/README.md`. npm names are unique, so the ids are too. `DocEntry.path`
|
|
348
|
+
keeps the registry path and `DocEntry.library` the package name. hoist-react entries have
|
|
349
|
+
`library: null` and unprefixed ids. Each library resolves its paths against its own root with
|
|
350
|
+
`resolveDocPath()`.
|
|
351
|
+
- **Scoped aliases.** hoist-react docs own every bare shortening. The resolver builds companion
|
|
352
|
+
auto-aliases only under the full and the unscoped package name, and a bare package name reaches
|
|
353
|
+
the library's `docs/README.md`. Where a companion alias would collide with a hoist-react one, the
|
|
354
|
+
hoist-react doc keeps it. Explicit companion aliases claim only the full prefix.
|
|
355
|
+
- **Relative links are rewritten.** `loadDocContent()` rewrites relative links in a companion doc,
|
|
356
|
+
so `../core/README.md` reads as `@xh/hoist-chat-kit/core/README.md`. Left as written, the link
|
|
357
|
+
would resolve to hoist-react's `core/README.md` with no error. A link to a file that is not a
|
|
358
|
+
served doc becomes a path under `sourcePath`. Links that leave the package, and links in code,
|
|
359
|
+
stay as written. Line numbers do not change, so section ranges still match.
|
|
360
|
+
- **Maintainer docs.** `loadLibrary()` drops entries with `mcpAudience: 'maintainers'` unless the
|
|
361
|
+
library's root is the app root. The rule applies to every registry, hoist-react's included, so
|
|
362
|
+
hoist-react can mark its own maintainer docs the same way.
|
|
363
|
+
- **Agents learn about libraries from the server.** `instructions.ts` names each library with its
|
|
364
|
+
version, description, and index id, and says that the symbol tools cover `@xh/hoist` only.
|
|
365
|
+
`hoist-ping`, `hoist-docs ping`, list output, and `hoist-docs index` also name the libraries.
|
|
366
|
+
- **Library guidance.** A registry can set `mcpInstructions`, a string or an array of lines. The
|
|
367
|
+
loader trims it and caps it at `MAX_LIBRARY_INSTRUCTIONS_CHARS`, and stores it on
|
|
368
|
+
`DocLibrary.instructions`. `instructions.ts` places it under the library's line and adds a
|
|
369
|
+
sentence that the guidance never overrides the user. The ping surfaces show it too, because CLI
|
|
370
|
+
agents never see server instructions. This is the one path by which a dependency's own text
|
|
371
|
+
reaches the instructions, so keep the cap and the framing.
|
|
372
|
+
- **Same schemas when none load.** The `library` filter on search and list, and the companion notes
|
|
373
|
+
in tool descriptions, appear only when a companion library loads.
|
|
374
|
+
- **Soft failures.** The loader skips a missing registry or doc file, or a path outside the
|
|
375
|
+
package, including a symlink to a file outside it. Registry and `package.json` fields of the
|
|
376
|
+
wrong type fall back to their defaults, and `loadCompanion()` turns any other error into a
|
|
377
|
+
warning, so a bad dependency never stops Hoist's own docs from loading. Each warning goes to
|
|
378
|
+
stderr and to `RegistryData.warnings`, which the ping surfaces report.
|
|
379
|
+
|
|
380
|
+
The symbol tools do not cover companion libraries. `data/ts-registry.ts` assumes one source root,
|
|
381
|
+
one `tsconfig.json`, and the `@xh/hoist/` import prefix.
|
|
382
|
+
|
|
323
383
|
## CLI Tools
|
|
324
384
|
|
|
325
385
|
The CLI tools provide the same documentation and TypeScript capabilities as the MCP server, but
|
|
@@ -409,6 +469,9 @@ path differs.
|
|
|
409
469
|
Claude Code starts stdio servers from the project root, so the path is relative to the app's root.
|
|
410
470
|
The server describes the `@xh/hoist` version installed in `node_modules`. After an install changes
|
|
411
471
|
that version, restart Claude Code (or reconnect with `/mcp`) so the server reloads.
|
|
472
|
+
The working directory also anchors [companion library](#companion-library-docs) discovery. Set
|
|
473
|
+
`HOIST_MCP_APP_ROOT` in `env` if the app's `package.json` is not in the project root or its
|
|
474
|
+
`client-app/` folder.
|
|
412
475
|
|
|
413
476
|
Toolbox is the exception, not the pattern. Its `.mcp.json` runs a wrapper script that prefers a
|
|
414
477
|
sibling `../hoist-react` checkout over `node_modules`, because Toolbox doubles as the framework's
|
|
@@ -472,6 +535,7 @@ most 2 results per doc. A default search costs under ~800 tokens. See
|
|
|
472
535
|
|-----------|------|----------|-------------|
|
|
473
536
|
| `query` | string | Yes | Two to four keywords, ideally the names the docs use (e.g. `"grid column renderer"`, `"persistWith"`) |
|
|
474
537
|
| `category` | enum | No | Filter: `package`, `concept`, `devops`, `conventions`, `index`, `all` (default) |
|
|
538
|
+
| `library` | enum | No | Only with companion libraries loaded. Limits results to one package, for example `@xh/hoist` |
|
|
475
539
|
| `limit` | number | No | Max sections, 1-10. Default: 5 |
|
|
476
540
|
|
|
477
541
|
**Example output** (`hoist-docs search "grid sorting" --limit 2`):
|
|
@@ -499,6 +563,11 @@ List all available documentation with descriptions, grouped by category.
|
|
|
499
563
|
| Parameter | Type | Required | Description |
|
|
500
564
|
|-----------|------|----------|-------------|
|
|
501
565
|
| `category` | enum | No | Filter: `package`, `concept`, `devops`, `conventions`, `index`, `all` (default) |
|
|
566
|
+
| `library` | enum | No | Only with companion libraries loaded. Limits the list to one package |
|
|
567
|
+
|
|
568
|
+
With companion libraries loaded, each library follows hoist-react's docs under its own heading.
|
|
569
|
+
Structured output adds `library` to each entry, and a `libraries` array with each package's name,
|
|
570
|
+
version, doc count, and index id.
|
|
502
571
|
|
|
503
572
|
#### `hoist-read-doc`
|
|
504
573
|
|
|
@@ -533,7 +602,8 @@ only when the input id differed from the canonical id.
|
|
|
533
602
|
#### `hoist-ping`
|
|
534
603
|
|
|
535
604
|
Verify the MCP server is running and responsive. Takes no parameters. Reports the indexed
|
|
536
|
-
`@xh/hoist` library version.
|
|
605
|
+
`@xh/hoist` library version. Also lists each companion library with its version, doc count, index
|
|
606
|
+
id, and guidance, and any companion library that failed to load.
|
|
537
607
|
|
|
538
608
|
### TypeScript Tools
|
|
539
609
|
|
|
@@ -776,6 +846,9 @@ prefix is also `hoist://docs/`. So `hoist://docs/routing.md` and `hoist://docs/d
|
|
|
776
846
|
both resolve to the same entry. For a friction-free read by bare ID, prefer the `hoist-read-doc`
|
|
777
847
|
tool.
|
|
778
848
|
|
|
849
|
+
Companion library docs use the same template with their prefixed ids, for example
|
|
850
|
+
`hoist://docs/@xh/hoist-chat-kit/core/README.md`. Reserved expansion passes the `@` through.
|
|
851
|
+
|
|
779
852
|
**Discovering available documents:** The `hoist-doc` resource supports `list` and `complete`
|
|
780
853
|
operations. MCP clients can enumerate all available doc IDs or get tab-completion suggestions.
|
|
781
854
|
|
|
@@ -892,6 +965,7 @@ just display without the extra hint. The `@mcpHint` tag is declared in the proje
|
|
|
892
965
|
| Change which owners have members indexed | `mcp/data/ts-registry.ts` (`shouldIndexClassMembers` / `shouldIndexInterfaceMembers`) |
|
|
893
966
|
| Raise the supported Node floor (tracks `engines` in hoist-dev-utils) | `@types/node` major in `package.json`, Node version under [Prerequisites](#prerequisites) |
|
|
894
967
|
| Change doc search ranking, or add a doc that deserves golden-set coverage | `mcp/data/doc-search.ts`, `mcp/data/doc-search.spec.ts` - then run `pnpm test:mcp` |
|
|
968
|
+
| Change companion library discovery, id prefixing, or alias scoping | `mcp/data/doc-registry.ts`, `mcp/util/paths.ts`, `mcp/data/doc-id-resolver.ts`, `docs/companion-library-docs.md` - then run `pnpm test:mcp` |
|
|
895
969
|
| Change symbol search ranking or output shape, or add an API that deserves golden-set coverage | `mcp/data/symbol-search.ts`, `mcp/formatters/typescript.ts`, `mcp/data/symbol-search.spec.ts` - then run `pnpm test:mcp` |
|
|
896
970
|
| Change the shape of `SymbolEntry`, `MemberIndexEntry`, or `SymbolDetail` | `CACHE_SCHEMA_VERSION` in `mcp/data/index-cache.ts` |
|
|
897
971
|
| Add a top-level directory that should be treated as internal in symbol search | `INTERNAL_TOP_DIRS` in `mcp/data/symbol-search.ts` |
|
|
@@ -910,6 +984,7 @@ typecheck. Both `pnpm lint` and `pnpm typecheck` cover `mcp/`, via its own ESLin
|
|
|
910
984
|
| Spec | Covers |
|
|
911
985
|
|------|--------|
|
|
912
986
|
| `data/doc-id-resolver.spec.ts` | Tolerant doc-id resolution |
|
|
987
|
+
| `data/companion-docs.spec.ts` | Companion library docs against a fixture app in a temp directory: app root resolution, discovery, id prefixing, load warnings, alias scoping and collisions, search and the library filter, library guidance, the MCP tools, resources, and instructions, and the CLI run from the app |
|
|
913
988
|
| `data/doc-sections.spec.ts` | Section parsing, section-name resolution, and full / section / outline reads |
|
|
914
989
|
| `data/doc-search.spec.ts` | Golden-set retrieval eval: top-3 hit rate (must stay at or above 85%), named experiment queries, and the default-search token budget (under 800) |
|
|
915
990
|
| `data/ts-registry.spec.ts` | TypeScript symbol and member lookup, cross-platform path handling |
|
package/mcp/cli/docs.ts
CHANGED
|
@@ -2,13 +2,16 @@
|
|
|
2
2
|
* CLI entry point for hoist-docs -- documentation search, listing, and reading.
|
|
3
3
|
*
|
|
4
4
|
* Wraps the same doc-registry logic used by the MCP server, producing identical
|
|
5
|
-
* output via shell commands instead of MCP tool calls.
|
|
5
|
+
* output via shell commands instead of MCP tool calls. Like the server, it serves companion
|
|
6
|
+
* library docs discovered from the package in the working directory (or its `client-app/`).
|
|
6
7
|
*/
|
|
7
8
|
import {Command} from 'commander';
|
|
8
9
|
|
|
9
|
-
import {
|
|
10
|
+
import {loadDocContent, loadRegistry} from '../data/doc-registry.js';
|
|
10
11
|
import {DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, searchDocs} from '../data/doc-search.js';
|
|
11
12
|
import {
|
|
13
|
+
formatCompanionStatus,
|
|
14
|
+
formatIndexFooter,
|
|
12
15
|
formatSearchResults,
|
|
13
16
|
formatDocList,
|
|
14
17
|
readDoc,
|
|
@@ -16,11 +19,33 @@ import {
|
|
|
16
19
|
toSearchDocsOutput,
|
|
17
20
|
toListDocsOutput
|
|
18
21
|
} from '../formatters/docs.js';
|
|
19
|
-
import {
|
|
22
|
+
import {resolveHoistVersion} from '../util/paths.js';
|
|
20
23
|
|
|
21
|
-
const
|
|
24
|
+
const data = loadRegistry(),
|
|
25
|
+
{entries: registry, mcpCategories} = data;
|
|
22
26
|
const VALID_CATEGORIES = [...mcpCategories.map(c => c.id), 'all'];
|
|
23
27
|
|
|
28
|
+
/**
|
|
29
|
+
* Resolve a `--library` value to a loaded package name. Accepts the full name or, for a scoped
|
|
30
|
+
* package, the name without its scope (`hoist-chat-kit` for `@xh/hoist-chat-kit`).
|
|
31
|
+
*/
|
|
32
|
+
function validateLibrary(value: string | undefined): string | undefined {
|
|
33
|
+
if (value == null) return undefined;
|
|
34
|
+
const lower = value.toLowerCase(),
|
|
35
|
+
match = data.libraries.find(
|
|
36
|
+
l =>
|
|
37
|
+
l.name.toLowerCase() === lower ||
|
|
38
|
+
l.name.toLowerCase().replace(/^@[^/]+\//, '') === lower
|
|
39
|
+
);
|
|
40
|
+
if (!match) {
|
|
41
|
+
console.error(
|
|
42
|
+
`Unknown library: "${value}". Loaded libraries: ${data.libraries.map(l => l.name).join(', ')}`
|
|
43
|
+
);
|
|
44
|
+
process.exit(1);
|
|
45
|
+
}
|
|
46
|
+
return match.name;
|
|
47
|
+
}
|
|
48
|
+
|
|
24
49
|
function validateCategory(value: string): string {
|
|
25
50
|
if (!VALID_CATEGORIES.includes(value)) {
|
|
26
51
|
console.error(
|
|
@@ -42,7 +67,9 @@ function validateLimit(value: string, min: number, max: number): string {
|
|
|
42
67
|
|
|
43
68
|
const program = new Command()
|
|
44
69
|
.name('hoist-docs')
|
|
45
|
-
.description(
|
|
70
|
+
.description(
|
|
71
|
+
'Search, list, and read hoist-react documentation, plus the docs of any companion libraries the current project opts in.'
|
|
72
|
+
)
|
|
46
73
|
.version('1.0.0');
|
|
47
74
|
|
|
48
75
|
program.addHelpText(
|
|
@@ -59,6 +86,8 @@ Examples:
|
|
|
59
86
|
hoist-docs read persistence --section "Built-in Model Support > GridModel"
|
|
60
87
|
Read one section
|
|
61
88
|
hoist-docs read v85 Read the v85 upgrade notes
|
|
89
|
+
hoist-docs read @xh/hoist-chat-kit/core Read a companion library doc (package-prefixed id)
|
|
90
|
+
hoist-docs list -L hoist-chat-kit List one companion library's docs
|
|
62
91
|
hoist-docs conventions Print coding conventions
|
|
63
92
|
hoist-docs index Print the documentation index
|
|
64
93
|
hoist-docs ping Confirm the CLI is wired up`
|
|
@@ -81,6 +110,7 @@ program
|
|
|
81
110
|
'Filter by category: ' + VALID_CATEGORIES.join(', '),
|
|
82
111
|
'all'
|
|
83
112
|
)
|
|
113
|
+
.option('-L, --library <name>', 'Limit to one library, e.g. "@xh/hoist" or "hoist-chat-kit"')
|
|
84
114
|
.option(
|
|
85
115
|
'-l, --limit <n>',
|
|
86
116
|
`Maximum number of sections (1-${MAX_SEARCH_LIMIT})`,
|
|
@@ -90,25 +120,31 @@ program
|
|
|
90
120
|
'--json',
|
|
91
121
|
'Output machine-readable JSON matching the MCP outputSchema instead of formatted text.'
|
|
92
122
|
)
|
|
93
|
-
.action(
|
|
94
|
-
|
|
95
|
-
|
|
123
|
+
.action(
|
|
124
|
+
(
|
|
125
|
+
query: string,
|
|
126
|
+
opts: {category: string; library?: string; limit: string; json?: boolean}
|
|
127
|
+
) => {
|
|
128
|
+
validateCategory(opts.category);
|
|
129
|
+
validateLimit(opts.limit, 1, MAX_SEARCH_LIMIT);
|
|
96
130
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
131
|
+
const results = searchDocs(registry, query, {
|
|
132
|
+
category: opts.category,
|
|
133
|
+
library: validateLibrary(opts.library),
|
|
134
|
+
limit: parseInt(opts.limit, 10)
|
|
135
|
+
});
|
|
101
136
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
137
|
+
if (opts.json) {
|
|
138
|
+
const structured = toSearchDocsOutput(query, results);
|
|
139
|
+
process.stdout.write(JSON.stringify(structured, null, 2) + '\n');
|
|
140
|
+
return;
|
|
141
|
+
}
|
|
107
142
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
143
|
+
let text = formatSearchResults(results, query);
|
|
144
|
+
if (results.length > 0) text += `\n\n${searchReadHint('cli')}`;
|
|
145
|
+
process.stdout.write(text + '\n');
|
|
146
|
+
}
|
|
147
|
+
);
|
|
112
148
|
|
|
113
149
|
//----------------------------------------------------------------------
|
|
114
150
|
// Subcommand: list
|
|
@@ -121,20 +157,22 @@ program
|
|
|
121
157
|
'Filter by category: ' + VALID_CATEGORIES.join(', '),
|
|
122
158
|
'all'
|
|
123
159
|
)
|
|
160
|
+
.option('-L, --library <name>', 'Limit to one library, e.g. "@xh/hoist" or "hoist-chat-kit"')
|
|
124
161
|
.option(
|
|
125
162
|
'--json',
|
|
126
163
|
'Output machine-readable JSON matching the MCP outputSchema instead of formatted text.'
|
|
127
164
|
)
|
|
128
|
-
.action((opts: {category: string; json?: boolean}) => {
|
|
165
|
+
.action((opts: {category: string; library?: string; json?: boolean}) => {
|
|
129
166
|
validateCategory(opts.category);
|
|
167
|
+
const filter = {category: opts.category, library: validateLibrary(opts.library)};
|
|
130
168
|
|
|
131
169
|
if (opts.json) {
|
|
132
|
-
const structured = toListDocsOutput(
|
|
170
|
+
const structured = toListDocsOutput(data, filter);
|
|
133
171
|
process.stdout.write(JSON.stringify(structured, null, 2) + '\n');
|
|
134
172
|
return;
|
|
135
173
|
}
|
|
136
174
|
|
|
137
|
-
let text = formatDocList(
|
|
175
|
+
let text = formatDocList(data, filter);
|
|
138
176
|
text += 'Read a doc with: hoist-docs read <id> [--section "<heading>" | --outline]';
|
|
139
177
|
process.stdout.write(text + '\n');
|
|
140
178
|
});
|
|
@@ -202,14 +240,17 @@ program
|
|
|
202
240
|
//----------------------------------------------------------------------
|
|
203
241
|
program
|
|
204
242
|
.command('index')
|
|
205
|
-
.description(
|
|
243
|
+
.description(
|
|
244
|
+
'Print documentation index -- shortcut for "read docs/README.md". Ends with the ids of any companion library indexes.'
|
|
245
|
+
)
|
|
206
246
|
.action(() => {
|
|
207
247
|
const entry = registry.find(e => e.id === 'docs/README.md');
|
|
208
248
|
if (!entry) {
|
|
209
249
|
console.error('Index document not found in registry.');
|
|
210
250
|
process.exit(1);
|
|
211
251
|
}
|
|
212
|
-
|
|
252
|
+
const footer = formatIndexFooter(data);
|
|
253
|
+
process.stdout.write(loadDocContent(entry) + (footer ? `\n---\n\n${footer}\n` : '\n'));
|
|
213
254
|
});
|
|
214
255
|
|
|
215
256
|
//----------------------------------------------------------------------
|
|
@@ -217,12 +258,16 @@ program
|
|
|
217
258
|
//----------------------------------------------------------------------
|
|
218
259
|
program
|
|
219
260
|
.command('ping')
|
|
220
|
-
.description(
|
|
261
|
+
.description(
|
|
262
|
+
'Verify the hoist-docs CLI is running and the doc registry loads. Lists any companion libraries whose docs are loaded.'
|
|
263
|
+
)
|
|
221
264
|
.action(() => {
|
|
222
265
|
// Registry is loaded at module init above; reaching here confirms it.
|
|
223
|
-
|
|
224
|
-
`hoist-docs CLI is running (@xh/hoist v${resolveHoistVersion()}, ${registry.length} docs indexed)
|
|
225
|
-
|
|
266
|
+
const lines = [
|
|
267
|
+
`hoist-docs CLI is running (@xh/hoist v${resolveHoistVersion()}, ${registry.length} docs indexed).`,
|
|
268
|
+
...formatCompanionStatus(data)
|
|
269
|
+
];
|
|
270
|
+
process.stdout.write(lines.join('\n') + '\n');
|
|
226
271
|
});
|
|
227
272
|
|
|
228
273
|
program.parse();
|
|
@@ -13,6 +13,11 @@
|
|
|
13
13
|
* Levenshtein or probabilistic ranking at the resolution layer.
|
|
14
14
|
* 3. Ambiguity surfaces. Auto-aliases that map to more than one entry are discarded.
|
|
15
15
|
*
|
|
16
|
+
* Companion library docs (ids prefixed with a package name, see `doc-registry.ts`) never claim a
|
|
17
|
+
* bare shortening. hoist-react docs own `core`, `index`, and the like. A companion library's
|
|
18
|
+
* aliases exist only under its prefix, in full (`@xh/hoist-chat-kit/core`) or unscoped
|
|
19
|
+
* (`hoist-chat-kit/core`), and its bare package name reaches its `docs/README.md` index.
|
|
20
|
+
*
|
|
16
21
|
* See the `resolveDocId` JSDoc below for the full tier ordering and rationale.
|
|
17
22
|
*/
|
|
18
23
|
import {log} from '../util/logger.js';
|
|
@@ -181,7 +186,7 @@ function suffixCandidates(input: string): string[] {
|
|
|
181
186
|
* Build the lowercased alias → canonical id map consumed by Tier 2.
|
|
182
187
|
*
|
|
183
188
|
* Auto-aliases are computed per entry; keys mapping to more than one distinct
|
|
184
|
-
* canonical id are dropped as ambiguous. Explicit aliases from `entry.aliases`
|
|
189
|
+
* canonical id are dropped as ambiguous, unless exactly one of them is a hoist-react doc. Explicit aliases from `entry.aliases`
|
|
185
190
|
* are layered in afterward and override the auto-generated ones for the same key.
|
|
186
191
|
*/
|
|
187
192
|
function buildAliasMap(registry: DocEntry[]): Map<string, string> {
|
|
@@ -189,7 +194,7 @@ function buildAliasMap(registry: DocEntry[]): Map<string, string> {
|
|
|
189
194
|
const autoCandidates = new Map<string, Set<string>>();
|
|
190
195
|
for (const entry of registry) {
|
|
191
196
|
const canonicalLower = entry.id.toLowerCase();
|
|
192
|
-
for (const key of autoAliasesFor(entry
|
|
197
|
+
for (const key of autoAliasesFor(entry)) {
|
|
193
198
|
const lower = key.toLowerCase();
|
|
194
199
|
if (lower === canonicalLower) continue;
|
|
195
200
|
const set = autoCandidates.get(lower) ?? new Set<string>();
|
|
@@ -198,11 +203,16 @@ function buildAliasMap(registry: DocEntry[]): Map<string, string> {
|
|
|
198
203
|
}
|
|
199
204
|
}
|
|
200
205
|
|
|
201
|
-
// Stage 2: keep only unambiguous auto-aliases.
|
|
202
|
-
|
|
206
|
+
// Stage 2: keep only unambiguous auto-aliases. hoist-react docs own any key they share with
|
|
207
|
+
// companion library docs - e.g. hoist's `grid` against the index of a package `@acme/grid`.
|
|
208
|
+
const finalMap = new Map<string, string>(),
|
|
209
|
+
hoistIds = new Set(registry.filter(e => e.library == null).map(e => e.id));
|
|
203
210
|
for (const [key, ids] of autoCandidates) {
|
|
211
|
+
const hoistOwners = [...ids].filter(id => hoistIds.has(id));
|
|
204
212
|
if (ids.size === 1) {
|
|
205
213
|
finalMap.set(key, [...ids][0]);
|
|
214
|
+
} else if (hoistOwners.length === 1) {
|
|
215
|
+
finalMap.set(key, hoistOwners[0]);
|
|
206
216
|
} else {
|
|
207
217
|
log.debug(`Discarding ambiguous auto-alias "${key}" (matches: ${[...ids].join(', ')})`);
|
|
208
218
|
}
|
|
@@ -214,7 +224,11 @@ function buildAliasMap(registry: DocEntry[]): Map<string, string> {
|
|
|
214
224
|
const canonicalLookup = new Set(registry.map(e => e.id.toLowerCase()));
|
|
215
225
|
const claimedByExplicit = new Set<string>();
|
|
216
226
|
for (const entry of registry) {
|
|
217
|
-
|
|
227
|
+
// A companion library's explicit aliases claim only its full package-name prefix. The
|
|
228
|
+
// unscoped forms are auto-aliases, dropped if two libraries share an unscoped name.
|
|
229
|
+
const explicit = (entry.aliases ?? []).map(a =>
|
|
230
|
+
entry.library == null ? a : `${entry.library}/${a}`
|
|
231
|
+
);
|
|
218
232
|
for (const a of explicit) {
|
|
219
233
|
const lower = a.toLowerCase();
|
|
220
234
|
// Warn if the alias collides with another entry's canonical id --
|
|
@@ -241,7 +255,7 @@ function buildAliasMap(registry: DocEntry[]): Map<string, string> {
|
|
|
241
255
|
}
|
|
242
256
|
|
|
243
257
|
/**
|
|
244
|
-
* Compute auto-alias candidates for a single
|
|
258
|
+
* Compute auto-alias candidates for a single entry, scoped under its library prefix.
|
|
245
259
|
*
|
|
246
260
|
* Examples:
|
|
247
261
|
* `cmp/grid/README.md` → `cmp/grid/README`, `cmp/grid`, `grid`
|
|
@@ -252,11 +266,26 @@ function buildAliasMap(registry: DocEntry[]): Map<string, string> {
|
|
|
252
266
|
* `upgrade-notes/v85-upgrade-notes`,
|
|
253
267
|
* `v85-upgrade-notes`,
|
|
254
268
|
* `v85`
|
|
269
|
+
* `@xh/hoist-chat-kit/core/README.md` (path `core/README.md`) →
|
|
270
|
+
* `@xh/hoist-chat-kit/core`, `hoist-chat-kit/core`, `hoist-chat-kit/core/README.md`, ...
|
|
271
|
+
* `@xh/hoist-chat-kit/docs/README.md` additionally → `@xh/hoist-chat-kit`, `hoist-chat-kit`
|
|
255
272
|
*/
|
|
256
|
-
function autoAliasesFor(
|
|
273
|
+
function autoAliasesFor(entry: DocEntry): string[] {
|
|
274
|
+
if (entry.library == null) return pathAliasesFor(entry.path);
|
|
275
|
+
|
|
276
|
+
// Also the path itself (giving the unscoped form of the id, `hoist-chat-kit/core/README.md`)
|
|
277
|
+
// and the explicit aliases, which claim only the full prefix in Stage 3.
|
|
278
|
+
const out = scoped(entry, [...pathAliasesFor(entry.path), entry.path, ...entry.aliases]);
|
|
279
|
+
// A bare package name reaches the library's index.
|
|
280
|
+
if (entry.path === 'docs/README.md') out.push(...libraryPrefixes(entry.library));
|
|
281
|
+
return out;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/** Shortenings of a registry path, before any library scoping. */
|
|
285
|
+
function pathAliasesFor(path: string): string[] {
|
|
257
286
|
const out = new Set<string>();
|
|
258
287
|
|
|
259
|
-
const noMd =
|
|
288
|
+
const noMd = path.endsWith('.md') ? path.slice(0, -3) : path;
|
|
260
289
|
out.add(noMd);
|
|
261
290
|
|
|
262
291
|
const noReadme = noMd.endsWith('/README') ? noMd.slice(0, -'/README'.length) : noMd;
|
|
@@ -275,12 +304,24 @@ function autoAliasesFor(id: string): string[] {
|
|
|
275
304
|
}
|
|
276
305
|
|
|
277
306
|
// Version shorthand for upgrade notes.
|
|
278
|
-
const versionMatch =
|
|
307
|
+
const versionMatch = path.match(/\/v(\d+)-upgrade-notes\.md$/);
|
|
279
308
|
if (versionMatch) out.add(`v${versionMatch[1]}`);
|
|
280
309
|
|
|
281
310
|
return [...out];
|
|
282
311
|
}
|
|
283
312
|
|
|
313
|
+
/** Prefix aliases with both the full and the unscoped name of the entry's library. */
|
|
314
|
+
function scoped(entry: DocEntry, aliases: string[]): string[] {
|
|
315
|
+
const prefixes = libraryPrefixes(entry.library!);
|
|
316
|
+
return aliases.flatMap(a => prefixes.map(p => `${p}/${a}`));
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/** `@scope/name` → [`@scope/name`, `name`]. An unscoped name yields itself only. */
|
|
320
|
+
function libraryPrefixes(library: string): string[] {
|
|
321
|
+
const unscoped = library.replace(/^@[^/]+\//, '');
|
|
322
|
+
return unscoped === library ? [library] : [library, unscoped];
|
|
323
|
+
}
|
|
324
|
+
|
|
284
325
|
//------------------------------------------------------------------
|
|
285
326
|
// Fallback: suggestions
|
|
286
327
|
//------------------------------------------------------------------
|