feat(tooling): pf-4720 pf-api collections

CONTRIBUTING.md

@@ -193,13 +193,19 @@ The `Node.js` engine requirements are updated on a predictable biannual schedule
 
 ### Project maintenance
 
+For information on project development maintenance tasks, refer to [Project development maintenance in docs/development.md](./docs/development.md#project-development-maintenance).
+
+#### Collection updates/reseeding
+
+For detailed collection reseeding steps, see [Updating collections](./docs/development.md#updating-collections) in the development guide.
+
 #### Releases and post-release review
 
 Full maintainer process: **[Releasing the MCP](./docs/development.md#releasing-the-mcp)** in the development guide. Day-to-day commits use [conventional commits](#pull-request-commits-messaging) to feed [CHANGELOG.md](./CHANGELOG.md).
 
 After each release, run the [post-release review](./docs/development.md#post-release-review) checklist. **CI** is the automated gate; negative findings can be filed as **GitHub Issues** for triage.
 
-For release steps, collection updates, and other maintainer tasks, see [Project development maintenance](./docs/development.md#project-development-maintenance) in the development guide.
+For detailed release steps, see [Project development maintenance](./docs/development.md#project-development-maintenance) in the development guide.
 
 ## AI agent
 

cspell.config.json

@@ -27,6 +27,7 @@
     "sandboxing",
     "sparkline",
     "streamable",
+    "symref",
     "tmpfs",
     "treeify",
     "unrepresentable",

docs/development.md

@@ -427,6 +427,36 @@ These terms describe **how tools and their related properties are represented**
 - **`Zod schema`**: A Zod schema instance. Loosely detected with `isZodSchema` (Zod 4 `_zod` / public `.def`, Zod 3 `_def`).
 - **`Raw Zod shape` (`ZodRawShapeCompat`)**: A **non-empty** plain object whose **values** are Zod schemas; keys are field names. An empty `{}` is **not** a raw Zod shape. Detected with `isZodRawShape`.
 
+## MCP collections
+
+Internal and custom collections implement a `McpCollection` tuple structure:
+
+```typescript
+type McpCollection = [
+  name: string,
+  config: { title?: string },
+  handler: (arg?: unknown) => McpCollectionResult | Promise<McpCollectionResult>,
+  _config?: {
+    initial?: McpCollectionResult | (() => McpCollectionResult | Promise<McpCollectionResult>);
+    runParallel?: `#${string}`;
+    runSchedule?: { intervalMs?: number; cancelMs?: number; delayStartMs?: number; continueOnError?: boolean; repeat?: number; };
+    retainLastViable?: boolean | ((context) => boolean | Promise<boolean>);
+    isRequired?: boolean;
+  }
+];
+```
+
+#### Tuple configuration options
+
+- **`name`** (`string`): Unique identifier for the collection (e.g., `'patternfly-docs'`).
+- **`config`** (`object`): Plugin-visible metadata, such as `title`.
+- **`handler`** (`function`): Sync, or async, function returning an `McpCollectionResult` object containing `{ records: [...] }`.
+- **`_config.initial`**: Synchronous or async initial data loader executed at server startup ($t=0$) before scheduled tasks or worker threads run.
+- **`_config.runParallel`**: Subpath import specifier (`#specifier`) used to execute the collection handler in a background worker pool thread (`server.workerPool`).
+- **`_config.runSchedule`**: Configuration for recurring background refresh intervals via `deferTask`.
+- **`_config.retainLastViable`**: Retains previously loaded valid records if an update attempt fails or returns an empty payload.
+- **`_config.isRequired`**: Controls whether server startup requires this collection to be populated.
+
 ## Initial troubleshooting
 
 ### Tool plugins
@@ -450,7 +480,7 @@ These terms describe **how tools and their related properties are represented**
 
 ## Project development maintenance
 
-For information on build maintenance, refer to [Maintenance in CONTRIBUTING.md](../CONTRIBUTING.md#nodejs-engine-bumps).
+For information on general build maintenance, refer to [Maintenance in CONTRIBUTING.md](../CONTRIBUTING.md#nodejs-engine-bumps).
 
 ### Releasing the MCP
 
@@ -506,11 +536,19 @@ Negative audit findings should have a **GitHub Issue** opened. Link the release
 
 Not every observation is a bug: link checks, upstream blips, and environment-specific behavior can be **false positives**. Use an issue for **triage** when unsure (“investigate whether X is real”) rather than silent fixes or a separate audit log.
 
-### How collection and source data get updated
+### Updating collections
+
+The server maintains multiple record collections that provide documentation and schemas to a consuming LLM. Each collection source follows its own maintenance lifecycle.
+
+#### General collection reseeding
+
+When PatternFly releases new documentation or component features, reseed the embedded local collection data:
+- `npm run build:collections`: Runs the complete crawler and manifest update pipeline and runs collection tests.
+- `npm run build:collections-api`: Updates `src/collection.patternFlyApi.json` and outputs CSV diffs to `reports/`.
 
-The server maintains multiple record collections that provide documentation and schemas to a consuming LLM. Each collection source follows its own maintenance lifecycle:
+#### Unique collections
 
-#### 1. Embedded documentation collection (`src/docs.json`)
+##### 1. Embedded documentation collection (`src/docs.json`)
 
 > A large percentage of `docs.json` records are being moved into the PatternFly API. In the near future, `docs.json` will be renamed and incorporated into a support collection for one-off records.
 
@@ -520,18 +558,30 @@ The original curated Markdown collection. It pins remote repository URLs to spec
 - **Validation**: Ensure all raw URLs are HTTPS, match the domain whitelist in `src/options.defaults.ts`, and return 2xx responses.
 - **Testing**: Run `npm test` and update `baseHashes` and the Repository Breakdown table in `src/__tests__/docs.json.test.ts` whenever refs change.
 
-#### 2. Pre-built API collection (`src/collection.patternFlyApi.json`)
+##### 2. Pre-built API collection (`src/collection.patternFlyApi.json`)
 
 The server packages pre-seeded API endpoints to enable instant server startup without network overhead.
 
-- **Update command**:
+- **Update commands**:
   ```bash
+  # Reseed the API collection and run collection test suites
   npm run build:collections
+
+  # Reseed the API collection
+  npm run build:collections-api
+
+  # Run collection test suites only
+  npm run test:collections
+
+  # Run collection test suites in watch mode
+  npm run test:collections-dev
   ```
-- **Execution**: Crawls live PatternFly API endpoints, filters quality records, updates `src/collection.patternFlyApi.json`, and executes collection-specific tests.
+- **Execution**: Crawls live PatternFly API endpoints via `apiSpider`, filters low-quality records, compresses content into `src/collection.patternFlyApi.json`, and outputs structured console diffs and timestamped CSV audit reports to `reports/YYYYMMDD-collection.patternFlyApi.report.csv`.
+- **Configuration & Environment Overrides**:
+  - `UPDATE_COLLECTIONS=true`: Required environment flag to execute collection builds directly.
 - **When to run**: When PatternFly publishes new releases, when updating metadata/quality filters, or as part of a general maintenance cycle.
 
-#### 3. Component schemas (`@patternfly/patternfly-component-schemas`)
+##### 3. Component schemas (`@patternfly/patternfly-component-schemas`)
 
 > A large percentage of Component schemas have been moved into the PatternFly API and are also being considered for incorporation into PatternFly React architecture and may be completely superseded in the future.
 
@@ -541,7 +591,7 @@ Component JSON schemas provide runtime prop definitions, default values, and typ
 - **Validation**: Verified through `src/collection.patternFlySchemas.ts` and automated unit tests.
 - **When to run**: When [PatternFly Component Schemas repo](https://github.com/patternfly/patternfly-component-schemas) publishes a new release.
 
-#### 4. Red Hat AI Handbook (`src/collection.aiHandbook.ts`)
+##### 4. Red Hat AI Handbook (`src/collection.aiHandbook.ts`)
 
 > The AI Handbook is a support collection since its content goes beyond PatternFly towards AI-specific patterns at an organizational and enterprise level.
 
@@ -550,36 +600,6 @@ Collection of specialized guides and AI patterns that are fetched dynamically at
 - **Update workflow**: Synchronized on runtime from the [Red Hat AI Handbook repo](https://github.com/rh-uxd/ai-handbook).
 - **Validation**: Verified through automated unit tests.
 
-### Collection authoring and specification
-
-Internal and custom collections implement the `McpCollection` tuple structure:
-
-```typescript
-type McpCollection = [
-  name: string,
-  config: { title?: string },
-  handler: (arg?: unknown) => McpCollectionResult | Promise<McpCollectionResult>,
-  _config?: {
-    initial?: McpCollectionResult | (() => McpCollectionResult | Promise<McpCollectionResult>);
-    runParallel?: `#${string}`;
-    runSchedule?: { intervalMs?: number; cancelMs?: number; delayStartMs?: number; continueOnError?: boolean; repeat?: number; };
-    retainLastViable?: boolean | ((context) => boolean | Promise<boolean>);
-    isRequired?: boolean;
-  }
-];
-```
-
-#### Tuple configuration options
-
-- **`name`** (`string`): Unique identifier for the collection (e.g., `'patternfly-docs'`).
-- **`config`** (`object`): Plugin-visible metadata, such as `title`.
-- **`handler`** (`function`): Sync, or async, function returning an `McpCollectionResult` object containing `{ records: [...] }`.
-- **`_config.initial`**: Synchronous or async initial data loader executed at server startup ($t=0$) before scheduled tasks or worker threads run.
-- **`_config.runParallel`**: Subpath import specifier (`#specifier`) used to execute the collection handler in a background worker pool thread (`server.workerPool`).
-- **`_config.runSchedule`**: Configuration for recurring background refresh intervals via `deferTask`.
-- **`_config.retainLastViable`**: Retains previously loaded valid records if an update attempt fails or returns an empty payload.
-- **`_config.isRequired`**: Controls whether server startup requires this collection to be populated.
-
 ## In-progress and future work
 
 For more information on our development roadmap, including "in-progress" and "future" work, please refer to the [Architecture & Roadmap](./architecture.md#roadmap) documentation.

eslint.config.js

@@ -127,7 +127,9 @@ export default [
   {
     files: [
       'scripts/**/*.ts',
-      'scripts/**/*.js'
+      'scripts/**/*.js',
+      'tooling/**/*.ts',
+      'tooling/**/*.js'
     ],
     rules: {
       'no-console': 0,

guidelines/README.md

@@ -37,6 +37,7 @@ Agents should use these phrases as signals to consult specific documentation and
 | **"review development guide"**      | Review `docs/development.md` for CLI, API, and plugin authoring.                                                                                       |
 | **"create an example tool plugin"** | Review `guidelines/agent_coding.md`, `docs/development.md`, `docs/examples/*`, and `src/*` for context, coding standards, and existing example formats. |
 | **"add documentation links"** / **"add doc entries"** / **"register docs"** / **"update docs.json"** / **"contribute to docs.json"** | Follow `guidelines/skills/add-docs-links/SKILL.md`: docs.json format, duplicate check, raw URL confirmation, then run unit tests and update meta. |
+| **"reseed collections"** / **"update collections"** / **"build collections"** | Follow `docs/development.md#updating-collections`: run `npm run build:collections` (or `build:collections-api`) to sync API records. |
 | **"review zod"** / **"zod upgrade"** / **"zod integration review"** / **"zod update report"** | Follow `guidelines/skills/review-zod-integration/SKILL.md`: release notes vs codebase, tests, report at `reports/YYYYMMDD-HHMMSS-zod-{semver}-update-report.md` (UTC). |
 | **"troubleshoot server"** / **"debug server"** | Review `docs/usage.md#troubleshooting` and the PatternFly MCP server resource `patternfly://context` |
 

jest.config.ts

@@ -72,9 +72,10 @@ export default {
       ...baseConfig
     },
     {
-      displayName: 'collections',
-      roots: ['<rootDir>/tests/scripts'],
-      testMatch: ['<rootDir>/tests/scripts/**/*collection*.test.ts'],
+      displayName: 'tooling:collections',
+      roots: ['<rootDir>/tooling/collections'],
+      testMatch: ['<rootDir>/tooling/collections/**/__tests__/**/*.test.ts'],
+      setupFilesAfterEnv: ['<rootDir>/jest.setupTests.ts'],
       ...baseConfig
     },
     {

package.json

@@ -35,7 +35,8 @@
     "build": "npm run build:clean; npm run test:types; pkgroll",
     "build:clean": "rm -rf dist",
     "build:watch": "npm run build -- --watch",
-    "build:collections": "UPDATE_COLLECTIONS=true tsx ./scripts/update.collection.patternFlyApi.ts && NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects collections",
+    "build:collections": "npm run build:collections-api && jest --selectProjects tooling:collections",
+    "build:collections-api": "UPDATE_COLLECTIONS=true tsx ./tooling/collections/update.patternFlyApi.ts",
     "container:build": "bash ./scripts/container.build.sh",
     "container:start": "bash ./scripts/container.run.sh",
     "release": "changelog --non-cc --link-url https://github.com/patternfly/patternfly-mcp.git",
@@ -45,15 +46,16 @@
     "test:audit": "NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects audit",
     "test:audit-container": "npm run container:build && jest --selectProjects audit:container",
     "test:ci": "npm test -- --coverage",
-    "test:collections": "NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects collections",
+    "test:collections": "jest --selectProjects tooling:collections",
+    "test:collections-dev": "npm run test:collections -- --watchAll",
     "test:dev": "npm test -- --watchAll",
     "test:integration": "npm run build && jest --selectProjects package && NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects e2e",
     "test:integration-dev": "npm run test:integration -- --watchAll",
     "test:lint": "eslint .",
     "test:lint-fix": "eslint . --fix",
     "test:package": "npm run build && jest --selectProjects package",
     "test:spell-docs": "cspell './README.md' './CONTRIBUTING.md' './GOVERNANCE.md' './SECURITY.md' './docs/**/*.md' './guidelines/**/*.md' './docs/**/*.ts' './docs/**/*.js' --config ./cspell.config.json --fail-fast",
-    "test:spell": "cspell './src/**/*.ts' './tests/**/*.ts' --exclude './src/**/*test*' --exclude './tests/**/*test*' --config ./cspell.config.json --fail-fast",
+    "test:spell": "cspell './src/**/*.ts' './tests/**/*.ts' './tooling/**/*.ts' --exclude './src/**/*test*' --exclude './tests/**/*test*' --exclude './tooling/**/*test*' --config ./cspell.config.json --fail-fast",
     "test:types": "tsc --noEmit",
     "prepare": "npm run build",
     "prepack": "npm run build"