fix: Simplify build pipeline and remove dead script code

- Wire yarn build:merchandising-api to build-with-enhanced-schema.js so
  the production build always fetches a fresh schema and injects descriptions
- Delete inject-descriptions.js (unused; logic lives in fetch-and-enhance-schema.js)
- Remove dead code in build-with-enhanced-schema.js (redundant require, unused export)
- Remove unused generateConfig variable in run-spectaql-with-cleanup.js
- Remove injectDescriptions from fetch-and-enhance-schema.js exports (not used externally)
- Update README.md and spectaql/README.md to reflect the simplified build workflow
- Rebuild index.html with latest enhanced schema

Author: meker12

README.md

@@ -60,7 +60,7 @@ If you have questions, open an issue and ask us. We look forward to hearing from
 
 ## GraphQL API reference generator
 
-The Merchandising GraphQL API reference is generated using [SpectaQL](https://github.com/anvilco/spectaql). It uses live introspection against the GraphQL endpoint and a metadata overlay to filter the schema down to the documented queries and types.
+The Merchandising GraphQL API reference is generated using [SpectaQL](https://github.com/anvilco/spectaql). It fetches the live schema via introspection, injects custom descriptions from a metadata overlay, and filters the schema down to the include only the queries and types supported by Adobe Commerce Optimizer catalog service operations.
 
 ### Quick start
 
@@ -90,10 +90,10 @@ To generate a live preview during local development, run: `yarn dev:merchandisin
 If the schema or metadata descriptions change, rebuild and test the API reference locally:
 
 1. Create a branch from `main`.
-2. Regenerate the API reference using the enhanced build (includes custom descriptions):
+2. Regenerate the API reference:
 
    ```bash
-   node scripts/build-with-enhanced-schema.js
+   yarn build:merchandising-api
    ```
 
 3. Verify the output in your browser.

package.json

@@ -33,7 +33,7 @@
     "test": "remark src/pages --frail",
     "build:admin-api": "spectaql --target-file index.html --config spectaql/config-admin.yml",
     "dev:admin-api": "spectaql --target-file index.html --config spectaql/config-admin.yml --development-mode",
-    "build:merchandising-api": "node scripts/run-spectaql-with-cleanup.js --target-file index.html --config spectaql/config-merchandising-temp.yml",
+    "build:merchandising-api": "node scripts/build-with-enhanced-schema.js",
     "dev:merchandising-api": "node scripts/run-spectaql-with-cleanup.js --target-file index.html --config spectaql/config-merchandising-temp.yml --development-mode",
     "build:graphql": "yarn build:admin-api && yarn build:merchandising-api",
     "lint": "docker run --rm -e RUN_LOCAL=true --env-file .github/super-linter.env -v \"$PWD\":/tmp/lint github/super-linter:slim-v5"

scripts/build-with-enhanced-schema.js

@@ -21,8 +21,6 @@ async function buildWithEnhancedSchema() {
 
     // Step 2: Generate SpectaQL config pointing to the enhanced schema
     console.log('🚀 Step 2: Generating SpectaQL configuration...');
-    require('./generate-spectaql-config');
-    
     const fs = require('fs');
     const { tempConfigPath } = require('./generate-spectaql-config');
     let tempConfig = fs.readFileSync(tempConfigPath, 'utf8');
@@ -88,9 +86,4 @@ async function buildWithEnhancedSchema() {
   }
 }
 
-// Run if called directly
-if (require.main === module) {
-  buildWithEnhancedSchema();
-}
-
-module.exports = { buildWithEnhancedSchema };
+buildWithEnhancedSchema();

scripts/fetch-and-enhance-schema.js

@@ -323,4 +323,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { main, injectDescriptions };
+module.exports = { main };

scripts/inject-descriptions.js

@@ -21,7 +21,6 @@ if (args.length === 0) {
 
 // First, generate the config file
 console.log('Generating SpectaQL configuration...');
-const generateConfig = require('./generate-spectaql-config');
 
 // Switch the temp config to use the enhanced schema file instead of the live URL.
 // The enhanced-schema.json contains descriptions injected from the metadata file

scripts/run-spectaql-with-cleanup.js

@@ -15,7 +15,7 @@ This directory contains [SpectaQL](https://github.com/anvilco/spectaql) configur
 |---|---|
 | `config-merchandising.yml` | Main SpectaQL config. Defines where to get the schema, what to document/hide, metadata paths, server info, intro text, theme, and the output directory (`static/graphql-api/merchandising-api`). |
 | `metadata-merchandising.json` | Filtering and description metadata. Marks unwanted queries, types, enums, unions, input objects, and interfaces as `undocumented: true` so SpectaQL excludes them. Also contains custom descriptions for query arguments under `FIELD_ARGUMENT`. |
-| `enhanced-schema.json` | Cached introspection result with custom descriptions already injected. Used for enhanced/offline builds instead of hitting the live endpoint. Generated by `scripts/fetch-and-enhance-schema.js`. |
+| `enhanced-schema.json` | Cached introspection result with custom descriptions already injected. Used for dev builds instead of hitting the live endpoint on every rebuild. Generated by `scripts/fetch-and-enhance-schema.js`. |
 | `config-merchandising-temp.yml` | Auto-generated temp config. A copy of the main config with `${TENANT_ID}` placeholders replaced by the actual environment variable value. Deleted automatically after the build. |
 | `config-admin.yml` | Configuration for the Admin API (reference not currently implemented). |
 | `comdox-theme/` | Custom SpectaQL theme. Contains Handlebars partial overrides (`type.hbs` and `_query-or-mutation-or-subscription.hbs`) that customize how types and queries render in the HTML output. |
@@ -25,10 +25,9 @@ This directory contains [SpectaQL](https://github.com/anvilco/spectaql) configur
 | Script | Role |
 |---|---|
 | `generate-spectaql-config.js` | Reads `config-merchandising.yml`, substitutes `${TENANT_ID}` from your `.env` file, writes the temp config, and cleans up on exit. |
-| `run-spectaql-with-cleanup.js` | Orchestrates the **standard build**: generates the temp config, spawns SpectaQL as a child process, then cleans up the temp file. This is what `yarn build:merchandising-api` runs. |
+| `run-spectaql-with-cleanup.js` | Orchestrates the **dev build**: generates the temp config, switches it to use `enhanced-schema.json`, spawns SpectaQL as a child process, then cleans up the temp file. This is what `yarn dev:merchandising-api` runs. |
 | `fetch-and-enhance-schema.js` | Fetches a live introspection result from the GraphQL endpoint, then injects custom descriptions from `metadata-merchandising.json` into the raw schema. Saves the result to `enhanced-schema.json`. |
-| `inject-descriptions.js` | Standalone module with the same description-injection logic, packaged as a SpectaQL preprocessing function. |
-| `build-with-enhanced-schema.js` | Orchestrates the **enhanced build**: (1) fetches and enhances the schema, (2) generates the temp config and rewrites it to point at `enhanced-schema.json` instead of the live URL, (3) runs SpectaQL. |
+| `build-with-enhanced-schema.js` | Orchestrates the **production build**: (1) fetches a fresh schema and injects descriptions from `metadata-merchandising.json`, (2) generates the temp config and rewrites it to point at `enhanced-schema.json` instead of the live URL, (3) runs SpectaQL. This is what `yarn build:merchandising-api` runs. |
 
 ### Environment and output
 
@@ -115,55 +114,38 @@ node scripts/fetch-and-enhance-schema.js
 
 ## Build commands
 
-There are two build paths. Both produce `static/graphql-api/merchandising-api/index.html`.
+Both build paths produce `static/graphql-api/merchandising-api/index.html`.
 
-### Standard build (live endpoint)
+### Production build
 
-Uses live introspection to fetch the schema and applies metadata filtering:
+Fetches a fresh schema from the live endpoint, injects all custom descriptions from `metadata-merchandising.json`, and runs SpectaQL:
 
 ```bash
 yarn build:merchandising-api
-
-# Or run in development mode with live preview
-yarn dev:merchandising-api
 ```
 
-What happens during a standard build:
+What happens during a production build:
 
-1. `generate-spectaql-config.js` reads the YAML config, replaces `${TENANT_ID}`, and writes the temp config
-1. `run-spectaql-with-cleanup.js` spawns SpectaQL with the temp config.
-1. SpectaQL introspects the live GraphQL endpoint.
-1. SpectaQL applies `metadata-merchandising.json` to filter out unwanted queries/types and inject descriptions via its built-in metadata system
+1. `fetch-and-enhance-schema.js` fetches the live introspection result and injects descriptions from `metadata-merchandising.json` directly into the schema JSON.
+1. The result is saved to `enhanced-schema.json`.
+1. `generate-spectaql-config.js` reads the YAML config, replaces `${TENANT_ID}`, and writes the temp config.
+1. The temp config is rewritten to use `introspectionFile: spectaql/enhanced-schema.json` instead of the live URL.
+1. SpectaQL runs against the local enhanced schema file.
 1. The custom theme partials override the default rendering.
 1. Output lands in `static/graphql-api/merchandising-api/index.html`.
 1. The temp config file is cleaned up.
 
-### Enhanced build (with description injection)
+### Dev build (fast iteration)
 
-The standard build uses the live schema as-is, so any query arguments that lack descriptions in the live schema appear blank. The enhanced build solves this by fetching the live schema, injecting the custom descriptions defined in `metadata-merchandising.json` (especially `FIELD_ARGUMENT` entries), and then running SpectaQL against the enhanced schema.
+Uses the existing `enhanced-schema.json` on disk — no live API call. Useful when iterating on metadata descriptions, theme templates, or config without waiting for a schema fetch:
 
 ```bash
-node scripts/build-with-enhanced-schema.js
-```
-
-You can also pass extra SpectaQL flags, for example:
-
-```bash
-node scripts/build-with-enhanced-schema.js --development-mode
+yarn dev:merchandising-api
 ```
 
-If you omit all arguments, it defaults to `--target-file index.html --config spectaql/config-merchandising-temp.yml`.
+This starts SpectaQL in watch mode with a live preview at `http://localhost:4400`. It rebuilds automatically when source files change.
 
-What happens during an enhanced build:
-
-1. `fetch-and-enhance-schema.js` fetches the live introspection result and injects `FIELD_ARGUMENT` descriptions directly into the schema JSON
-1. The result is saved to `enhanced-schema.json`.
-1. The temp config is generated and rewritten to use `introspectionFile: spectaql/enhanced-schema.json` instead of the live URL.
-1. SpectaQL runs against the local enhanced schema file.
-1. Output lands in `static/graphql-api/merchandising-api/index.html`.
-1. The temp config file is cleaned up.
-
-Use the enhanced build whenever `metadata-merchandising.json` includes custom descriptions that you want reflected in the generated API reference.
+> **Note:** The dev build does not refresh `enhanced-schema.json`. If the live schema has changed or you have updated `metadata-merchandising.json`, run `yarn build:merchandising-api` to get a fresh result.
 
 ### Update the cached schema only
 
@@ -173,24 +155,23 @@ To fetch and enhance the schema without running SpectaQL:
 node scripts/fetch-and-enhance-schema.js
 ```
 
-This saves the result to `enhanced-schema.json`. To use it for offline builds, the config already points to this file via `introspectionFile: spectaql/enhanced-schema.json`.
+This saves the result to `enhanced-schema.json` and is useful when you want to inspect the schema before building.
 
 ## Update the API reference
 
 If the schema or metadata descriptions change, rebuild and test the API reference locally:
 
 1. Create a branch from `main`.
-2. If you updated custom descriptions in `metadata-merchandising.json`, use the enhanced build:
-
-```bash
-node scripts/build-with-enhanced-schema.js
-```
+1. Make your changes to `metadata-merchandising.json`, theme templates, or config.
+1. Run the production build to regenerate the schema and documentation:
 
-Otherwise, use the standard build: `yarn build:merchandising-api`
+   ```bash
+   yarn build:merchandising-api
+   ```
 
-3. Open `static/graphql-api/merchandising-api/index.html` in your browser and verify the output.
-4. Commit the updated `index.html` and `enhanced-schema.json` files.
-5. After updates are approved, a documentation team member merges the PR and publishes the updates to the [developer site](https://developer.adobe.com/commerce/services/merchandising-services/).
+1. Open `static/graphql-api/merchandising-api/index.html` in your browser and verify the output.
+1. Commit the updated `index.html` and `enhanced-schema.json` files.
+1. After updates are approved, a documentation team member merges the PR and publishes the updates to the [developer site](https://developer.adobe.com/commerce/services/merchandising-services/).
 
 ## Generated output
 

spectaql/README.md

@@ -77228,6 +77228,6 @@
     }
   },
   "extensions": {
-    "request-id": "34e01da2-9625-4e49-aa0a-2c562effd918"
+    "request-id": "a75167ce-c2a3-4c78-82c4-d114a98c1411"
   }
 }