@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.
Files changed (93) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/build/types/cmp/grid/GridModel.d.ts +6 -0
  3. package/build/types/cmp/input/impl/LiveCommas.d.ts +21 -0
  4. package/build/types/cmp/viewmanager/ViewManagerModel.d.ts +4 -2
  5. package/build/types/core/XH.d.ts +2 -1
  6. package/build/types/core/model/HoistModel.d.ts +1 -0
  7. package/build/types/core/model/ManagedRefreshContextModel.d.ts +1 -0
  8. package/build/types/core/persist/PersistenceProvider.d.ts +3 -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/dash/DashViewSpec.d.ts +2 -1
  13. package/build/types/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.d.ts +1 -1
  14. package/build/types/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.d.ts +3 -2
  15. package/build/types/desktop/cmp/dash/container/impl/DashContainerContextMenu.d.ts +1 -1
  16. package/build/types/desktop/cmp/dash/impl/DashUtils.d.ts +35 -0
  17. package/build/types/desktop/cmp/grid/editors/impl/InlineEditorModel.d.ts +6 -1
  18. package/build/types/desktop/cmp/input/NumberInput.d.ts +5 -2
  19. package/build/types/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.d.ts +1 -2
  20. package/build/types/mobile/cmp/input/NumberInput.d.ts +5 -2
  21. package/build/types/svc/FetchService.d.ts +19 -0
  22. package/build/types/test-support/agGrid.d.ts +2 -0
  23. package/build/types/test-support/hoistCore.d.ts +7 -1
  24. package/build/types/test-support/index.d.ts +1 -0
  25. package/build/types/test-support/jsonBlobs.d.ts +130 -0
  26. package/build/types/test-support/testApp.d.ts +5 -2
  27. package/cmp/grid/Grid.ts +2 -2
  28. package/cmp/grid/GridModel.ts +14 -1
  29. package/cmp/grid/columns/Column.ts +3 -2
  30. package/cmp/input/impl/LiveCommas.ts +59 -0
  31. package/cmp/viewmanager/ViewManagerModel.ts +25 -7
  32. package/core/XH.ts +8 -3
  33. package/core/model/HoistModel.ts +4 -2
  34. package/core/model/Hooks.ts +1 -0
  35. package/core/model/ManagedRefreshContextModel.ts +5 -1
  36. package/core/persist/PersistenceProvider.ts +15 -1
  37. package/data/cube/View.ts +3 -9
  38. package/data/cube/impl/RowCache.ts +2 -2
  39. package/data/cube/row/BaseRow.ts +14 -1
  40. package/data/cube/row/ParentRow.ts +1 -1
  41. package/desktop/cmp/dash/DashViewSpec.ts +2 -1
  42. package/desktop/cmp/dash/README.md +6 -5
  43. package/desktop/cmp/dash/canvas/impl/DashCanvasContextMenu.ts +1 -1
  44. package/desktop/cmp/dash/canvas/impl/utils.ts +16 -51
  45. package/desktop/cmp/dash/canvas/widgetchooser/DashCanvasWidgetChooser.ts +37 -54
  46. package/desktop/cmp/dash/container/impl/DashContainerContextMenu.ts +8 -39
  47. package/desktop/cmp/dash/impl/DashUtils.ts +90 -0
  48. package/desktop/cmp/grid/editors/BooleanEditor.ts +2 -1
  49. package/desktop/cmp/grid/editors/DateEditor.ts +4 -1
  50. package/desktop/cmp/grid/editors/SelectEditor.ts +4 -1
  51. package/desktop/cmp/grid/editors/impl/InlineEditorModel.ts +17 -5
  52. package/desktop/cmp/input/NumberInput.ts +51 -12
  53. package/desktop/cmp/input/Select.ts +25 -7
  54. package/desktop/cmp/tab/TabSwitcher.ts +4 -6
  55. package/desktop/cmp/tab/dynamic/DynamicTabSwitcher.ts +4 -5
  56. package/desktop/cmp/tab/dynamic/DynamicTabSwitcherModel.ts +2 -7
  57. package/docs/README.md +2 -0
  58. package/docs/build-and-publish.md +21 -11
  59. package/docs/companion-library-docs.md +205 -0
  60. package/docs/doc-registry.json +9 -1
  61. package/docs/lifecycle-app.md +17 -0
  62. package/docs/lifecycle-models-and-services.md +2 -1
  63. package/docs/persistence.md +2 -0
  64. package/docs/telemetry.md +29 -0
  65. package/docs/unit-testing.md +54 -3
  66. package/docs/upgrade-notes/v89-upgrade-notes.md +7 -1
  67. package/docs/version-compatibility.md +2 -1
  68. package/icon/README.md +4 -1
  69. package/mcp/README.md +79 -4
  70. package/mcp/cli/docs.ts +75 -30
  71. package/mcp/data/doc-id-resolver.ts +50 -9
  72. package/mcp/data/doc-registry.ts +462 -44
  73. package/mcp/data/doc-search.ts +25 -6
  74. package/mcp/formatters/docs.ts +136 -36
  75. package/mcp/instructions.ts +69 -0
  76. package/mcp/resources/docs.ts +10 -8
  77. package/mcp/server.ts +7 -13
  78. package/mcp/tools/docs.ts +64 -18
  79. package/mcp/util/paths.ts +85 -2
  80. package/mobile/cmp/input/NumberInput.ts +42 -4
  81. package/package.json +19 -19
  82. package/public/msal-redirect-bridge.min.js +1 -1
  83. package/svc/FetchService.ts +38 -2
  84. package/svc/JsonBlobService.ts +7 -4
  85. package/svc/README.md +7 -3
  86. package/test-support/agGrid.ts +12 -2
  87. package/test-support/hoistCore.ts +32 -5
  88. package/test-support/index.ts +1 -0
  89. package/test-support/jsonBlobs.ts +543 -0
  90. package/test-support/setup.ts +8 -6
  91. package/test-support/testApp.ts +36 -7
  92. package/build/types/desktop/cmp/tab/impl/TabContextMenuItems.d.ts +0 -4
  93. 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 # Documentation inventory loader (reads docs/doc-registry.json)
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 and path traversal safety
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 {buildRegistry, loadDocContent} from '../data/doc-registry.js';
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 {resolveRepoRoot, resolveHoistVersion} from '../util/paths.js';
22
+ import {resolveHoistVersion} from '../util/paths.js';
20
23
 
21
- const {entries: registry, mcpCategories} = buildRegistry(resolveRepoRoot());
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('Search, list, and read hoist-react documentation.')
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((query: string, opts: {category: string; limit: string; json?: boolean}) => {
94
- validateCategory(opts.category);
95
- validateLimit(opts.limit, 1, MAX_SEARCH_LIMIT);
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
- const results = searchDocs(registry, query, {
98
- category: opts.category,
99
- limit: parseInt(opts.limit, 10)
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
- if (opts.json) {
103
- const structured = toSearchDocsOutput(query, results);
104
- process.stdout.write(JSON.stringify(structured, null, 2) + '\n');
105
- return;
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
- let text = formatSearchResults(results, query);
109
- if (results.length > 0) text += `\n\n${searchReadHint('cli')}`;
110
- process.stdout.write(text + '\n');
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(registry, mcpCategories, opts.category);
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(registry, mcpCategories, opts.category);
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('Print documentation index -- shortcut for "read docs/README.md".')
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
- process.stdout.write(loadDocContent(entry) + '\n');
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('Verify the hoist-docs CLI is running and the doc registry loads.')
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
- process.stdout.write(
224
- `hoist-docs CLI is running (@xh/hoist v${resolveHoistVersion()}, ${registry.length} docs indexed).\n`
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.id)) {
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
- const finalMap = new Map<string, string>();
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
- const explicit = entry.aliases ?? [];
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 canonical id.
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(id: string): string[] {
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 = id.endsWith('.md') ? id.slice(0, -3) : id;
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 = id.match(/\/v(\d+)-upgrade-notes\.md$/);
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
  //------------------------------------------------------------------