@wootsup/yt-builder-mcp 1.12.0 → 2.0.0

package/README.md

@@ -63,29 +63,35 @@ The wizard auto-detects and configures the following clients:
 
 ## Tool surface (gateway model)
 
-The server catalogues **52 tools + 2 gateways = 54 reachable** end-to-end,
-of which **42 are advertised in `tools/list`** (well under Cursor's ~40-tool
+The server catalogues **60 tools + 2 gateways = 62 reachable** end-to-end,
+of which **49 are advertised in `tools/list`** (well under Cursor's ~40-tool
 cap — the 3-lane split keeps the advertised surface small while every
 catalogued tool stays callable):
 
 - **2 direct top-level tools** (always in `tools/list`):
   `yootheme_builder_health`, `yootheme_builder_diagnose`. The
   "the gateway itself might be broken" escape hatch.
-- **38 essential forwarded tools** (always in `tools/list`): the most-used
+- **45 essential forwarded tools** (always in `tools/list`): the most-used
   reads and writes (`pages_list`, `pages_create`, `pages_delete`,
-  `page_dynamize`, `get_etag`, `element_list`, `element_add`,
+  `pages_set_status`, `pages_restore` (the one correct way back from the
+  trash — a gateway-only placement would leave it discoverable only to a
+  caller who already knows it exists),
+  `page_generate_dynamic`, `get_etag`, `element_list`, `element_add`,
   `element_update_settings`, `sources_list`, `element_types_list`,
   `inspect_multi_items_binding`, the multi-site `sites_list` / `sites_test` /
-  `use_site`, and the bind→save→publish chain `element_bind_source` /
-  `page_save` / `page_publish`, among others).
-- **2 gateway tools** exposing the remaining **12 advanced tools**:
-  - `yootheme_builder_advanced` (write-capable) routes **all 12**
-    (`page_get_schema`, `element_unbind_source`,
-    `clean_implode_directives`, `inspect_sublayout`, `layout_query`,
+  `use_site`, `get_skill` (the full-guide retrieval tool), `modules_delete`
+  (the one gateway-only destructive tool that removes data outside the
+  layout tree, promoted so a host can gate it individually), and the
+  bind→save→publish→unbind chain `element_bind_source` / `page_save` /
+  `page_publish` / `element_unbind_source`, among others).
+- **2 gateway tools** exposing the remaining **13 advanced tools**:
+  - `yootheme_builder_advanced` (write-capable) routes **all 13**
+    (`clean_implode_directives`, `inspect_sublayout`, `layout_query`,
     `library_save_as`, `library_delete`, `local_content_types`,
-    `local_content_read`, `pages_audit`, `heading_outline`, `navigation`).
+    `local_content_read`, `pages_audit`, `heading_outline`, `navigation`,
+    `header_transparency_set`, `modules_update`, `modules_create`).
   - `yootheme_builder_advanced_read` (read-only-annotated) routes only the
-    **8 read-only** advanced tools (`page_get_schema`, `inspect_sublayout`,
+    **7 read-only** advanced tools (`inspect_sublayout`,
     `layout_query`, `local_content_types`, `local_content_read`,
     `pages_audit`, `heading_outline`, `navigation`), so MCP hosts can
     auto-allow pure inspection without a per-call write-approval prompt.
@@ -93,20 +99,13 @@ catalogued tool stays callable):
   (returns the schema) or `({ tool, arguments })` to execute.
 
 See `skills/yt-builder-mcp/SKILL.md` for the full catalog and canonical
-workflows, and `docs/TOOL-CATALOG.md` for an auto-generated reference.
-
-## Tool catalogue
-
-| Domain      | Count | Tools                                                                                                                                                                |
-|-------------|------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Health      |     2 | `health`, `diagnose`                                                                                                                                                |
-| Sites       |     2 | `sites_list`, `sites_test`                                                                                                                                          |
-| Pages       |     7 | `pages_list`, `page_get_layout`, `page_get_schema`, `template_summary`, `get_etag`, `page_save`, `page_publish`                                                     |
-| Elements    |     7 | `element_list`, `element_get`, `element_add`, `element_update_settings`, `element_move`, `element_clone`, `element_delete`                                          |
-| Sources     |     5 | `sources_list`, `element_get_binding`, `element_bind_source`, `element_unbind_source`, `inspect_multi_items_binding`                                                |
-| Inspection  |     3 | `element_types_list`, `element_type_get_schema`, `clean_implode_directives`                                                                                         |
-| Sublayout   |     1 | `inspect_sublayout` (F154 — fragment subtree + render-time inner-grid gate; advanced/gateway-routed)                                                                |
-| Gateway     |     2 | `advanced` (write, routes all 10 advanced tools), `advanced_read` (read-only, routes the 6 read-only advanced tools)                                                  |
+workflows, and `docs/TOOL-CATALOG.md` for an auto-generated, per-tool
+reference (regenerated from the live registry by
+`node scripts/extract-tools.mjs` — never hand-copied here, which is
+exactly why the numbers above stay accurate release over release; an
+earlier, hand-maintained domain-count table on this exact spot had
+drifted to less than half the real tool count and a stale gateway
+count before it was replaced with this pointer).
 
 All tool names are prefixed with `yootheme_builder_` at the MCP server boundary.
 
@@ -114,7 +113,18 @@ All tool names are prefixed with `yootheme_builder_` at the MCP server boundary.
 
 ```
 yt-builder-mcp setup            Interactive first-run wizard (default).
+yt-builder-mcp doctor           Diagnose connectivity (Node version, corporate
+                                 proxy/TLS, site reachability, bearer validity,
+                                 update status). Run this first when setup "hangs".
 yt-builder-mcp install-skill    Install the bundled agent skill.
+yt-builder-mcp uninstall        Remove yt-builder-mcp from configured AI clients
+  (alias: remove)               (and, optionally, the installed skill).
+yt-builder-mcp add-site         Add a site to the multi-site registry (see
+                                 "Multi-site setup" below).
+yt-builder-mcp list-sites       List configured sites (no network calls).
+yt-builder-mcp remove-site <id> Remove a site; auto-promotes the next as default.
+yt-builder-mcp set-default <id> Flip which configured site is the default.
+yt-builder-mcp test-site <id>   Probe /health + /etag for one configured site.
 yt-builder-mcp --version, -v    Print package version.
 yt-builder-mcp --help, -h       Show usage.
 ```
@@ -131,9 +141,9 @@ AI clients that follow the `~/AGENTS.md` discovery protocol. The
 single location keeps the skill discoverable across every supported
 client without per-client write logic.
 
-The skill ships with the 5 canonical workflows (build hero, bind
-source, clone section, diagnose 401, add custom element) plus a
-26-tool auto-generated catalog appendix.
+The skill ships with the 6 canonical workflows (build hero, bind
+source, clone section, diagnose 401, add custom element, SEO audit)
+plus a 60-tool auto-generated catalog appendix.
 
 ## MCPB bundle (Claude Desktop one-click install)
 
@@ -164,6 +174,11 @@ When launched by an AI client (or directly):
 | `YTB_MCP_PLATFORM` | No | Explicit platform hint: `wordpress` or `joomla`. Set to `joomla` when `YTB_MCP_SITE_URL` is an origin-only Joomla URL (no `/api/index.php/` in the path). Defaults to URL-shape auto-detection. |
 | `YTB_MCP_TIMEOUT_MS` | No | REST timeout (default 15000). |
 | `YTB_MCP_TEST_MODE` | No | `1` skips the stdio loop (smoke tests). |
+| `YTB_MCP_SITES_FILE` | No | Path to the multi-site registry (see "Multi-site setup" above). Defaults to `~/.config/yt-builder-mcp/sites.json`. |
+| `YTB_MCP_PROFILE` | No | Boots the server pinned to one `site_id` from the registry, for a one-MCP-entry-per-site setup. |
+| `YTB_MCP_EXTRA_HEADERS` | No | Extra HTTP headers merged into every outbound request (a WAF cookie, a corporate gateway secret, HTTP Basic-Auth, …). Either a JSON object (`{"X-WAF-Token":"abc"}`) or `Name: value` lines. An `Authorization` entry here is always dropped — the Bearer owns that header. |
+| `YTB_MCP_SITE_BASIC_AUTH` | No | `user:pass` for a site fronted by an HTTP Basic-Auth realm. Sent as the `Authorization: Basic …` header; the plugin Bearer then travels on `X-Authorization`. |
+| `YTB_MCP_VERSION` | No | Version-pin fallback used when `--pin` isn't passed at setup time (see "Corporate TLS interception / air-gapped installs"). |
 
 ## Manual MCP config (no wizard)
 
@@ -195,6 +210,58 @@ For a Joomla install at an origin-only URL, also set the platform hint:
 }
 ```
 
+## Multi-site setup (more than one WordPress/Joomla site)
+
+Instead of one `env` block per AI client, add every site once to a
+shared on-disk registry and address each by `site_id`:
+
+```bash
+npx -y @wootsup/yt-builder-mcp add-site \
+  --url https://shop.example.com --token "$YTB_TOKEN" \
+  --label "Shop" --site-id shop --default
+
+npx -y @wootsup/yt-builder-mcp add-site \
+  --url https://blog.example.com --token-ref "op://Vault/blog/token" \
+  --label "Blog" --site-id blog
+
+npx -y @wootsup/yt-builder-mcp list-sites
+npx -y @wootsup/yt-builder-mcp test-site shop
+npx -y @wootsup/yt-builder-mcp set-default blog
+npx -y @wootsup/yt-builder-mcp remove-site blog
+```
+
+`add-site` flags:
+
+| Flag | Required? | Description |
+|------|-----------|-------------|
+| `--url <site-url>` | Yes | Site base URL (WordPress or Joomla). |
+| `--token <bearer>` | One of these two | Plain Bearer key. Mutually exclusive with `--token-ref`. |
+| `--token-ref <op://…>` | One of these two | 1Password Secret Reference (`op://<vault>/<item>/<field>`) instead of a plain-text key. |
+| `--platform auto\|wordpress\|joomla` | No (default `auto`) | Explicit platform hint; `auto` is runtime-detected on first use. |
+| `--label "<text>"` | No | Human-readable label shown by `list-sites`. |
+| `--site-id <slug>` | No (default `default`) | Registry key used by every other multi-site command and by a tool call's optional `site_id` argument. |
+| `--default` | No | Mark this site as the default (the first added site becomes default automatically). |
+| `--yes` | No | Overwrite an existing `site_id` instead of failing. |
+| `--sites-file <path>` | No | Registry file to write, overriding `YTB_MCP_SITES_FILE` / the default path for this one call. |
+
+The registry lives at `~/.config/yt-builder-mcp/sites.json`
+(`$XDG_CONFIG_HOME/yt-builder-mcp/sites.json` when that variable is
+set). `YTB_MCP_SITES_FILE` is the switch that makes the server READ a
+registry at all: without it the server ignores `sites.json` entirely and
+runs off the single-site `YTB_MCP_SITE_URL` / `YTB_MCP_BEARER_TOKEN`
+pair. `setup` writes it for you, pointing at the registry it filled; set
+it by hand only to name a different path. When the file it names is
+missing or holds no sites, the server falls back to the single-site pair,
+so an unpopulated registry never costs you a working config.
+`YTB_MCP_PROFILE=<site_id>` boots the server
+pinned to one site from the registry — useful when you'd rather run
+one MCP entry per site than one shared multi-site entry.
+
+`uninstall` (alias `remove`) accepts `--all` (every detected client +
+the skill, no prompts), `--yes`/`-y` (skip the final confirmation),
+`--keep-skill` (remove client entries but leave the installed skill in
+place), and `--force`.
+
 ## Non-interactive CI usage
 
 For scripted / CI installs, pass the answers as flags and add
@@ -222,6 +289,36 @@ The wizard still runs its plugin-health + auth probes and uses the
 exit codes documented in the table below, so CI can branch on the
 exit code to detect whether the install actually succeeded.
 
+### Corporate TLS interception / air-gapped installs
+
+| Flag | Description |
+|------|-------------|
+| `--ca <path>` | Trust a corporate root CA `.pem` (writes `NODE_EXTRA_CA_CERTS=<path>` into the generated client config). |
+| `--use-system-ca` (or `--ca=system`) | Trust the OS certificate store instead of an exported file — zero-export, needs Node ≥ 22.15 (writes `NODE_OPTIONS=--use-system-ca`). |
+| `--pin <version>` | Pin the generated client config to an exact version (`npx -y @wootsup/yt-builder-mcp@<version>`) instead of the floating `@latest`. Falls back to the `YTB_MCP_VERSION` env var when omitted. |
+
+The interactive wizard auto-offers `--ca` / `--use-system-ca` the
+moment a probe fails with a TLS-inspection certificate error, so these
+flags are mainly for the non-interactive/CI path.
+
+### One-click setup (pickup mode)
+
+The host plugin's admin UI can hand the wizard a freshly-minted Bearer
+key directly, skipping the URL/token prompts entirely:
+
+```bash
+npx -y @wootsup/yt-builder-mcp setup \
+  --pickup https://example.com/wp-json/yt-builder-mcp/v1/setup/pickup \
+  --nonce "$NONCE" \
+  --client claude-desktop
+```
+
+The pickup URL and nonce are revealed together in wp-admin → Tools →
+"YT Builder MCP" (WordPress) or Administrator → Components → "YT
+Builder MCP" (Joomla). The pickup is IP-bound, single-use, and expires
+after 5 minutes; any `--url`/`--token` passed alongside `--pickup` are
+ignored (with a stderr warning).
+
 ## Exit codes (CLI)
 
 The CLI returns POSIX-style exit codes for scripting / CI:
@@ -234,12 +331,13 @@ The CLI returns POSIX-style exit codes for scripting / CI:
 | 3 | Auth probe failed and user declined to continue |
 | 4 | Write failed; configs rolled back |
 | 5 | Handshake failed; configs rolled back |
+| 6 | AI clients configured, but the site could not be recorded in `sites.json`; nothing rolled back |
 | 99 | Unhandled fatal in dispatcher |
 | 130 | User cancelled (SIGINT) |
 
 ## Documentation
 
-- [SKILL.md (bundled agent skill)](./skills/yt-builder-mcp/SKILL.md): 5 canonical workflows, gateway model, tool catalog
+- [SKILL.md (bundled agent skill)](./skills/yt-builder-mcp/SKILL.md): 6 canonical workflows, gateway model, tool catalog
 - [REST API Reference](https://wootsup.com/docs/mcp/yootheme-wordpress/)
 - [MCP Tool Reference](https://wootsup.com/docs/mcp/yootheme-wordpress/tools)
 

package/bin/node-floor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Type declaration for `node-floor.js`.
+ *
+ * That file is deliberately plain JavaScript outside the `src/` tree — its
+ * own docblock explains why: it guards the import that would otherwise throw
+ * while the module graph is being instantiated. `tsconfig.tests.json` still
+ * type-checks the tests that import it, and a `.js` module with no sibling
+ * declaration types as `any` there (TS7016) — this file is that declaration,
+ * kept in sync with the implementation by hand since the source itself
+ * cannot carry types without becoming the thing it guards against.
+ *
+ * @license MIT
+ */
+
+export declare const NODE_PREFLIGHT_FLOOR: readonly [number, number, number];
+export declare const UNSUPPORTED_NODE_MAJOR: number;
+export declare const NODE_TOO_OLD_EXIT: number;
+export declare const NODE_UNSUPPORTED_LINE_EXIT: number;
+
+export interface NodeRuntimeRefusal {
+    readonly exitCode: number;
+    readonly message: string;
+}
+
+export declare function nodeRuntimeRefusal(
+    versionString: string,
+    floor?: readonly [number, number, number],
+): NodeRuntimeRefusal | null;

package/bin/node-floor.js

@@ -0,0 +1,123 @@
+/**
+ * Refuse to run on a Node this package cannot work on, and say so in words the
+ * reader can act on.
+ *
+ * Why this cannot live in `dist/`: a dependency of the setup wizard uses a
+ * terminal-formatting helper from a Node builtin. Where the helper is missing
+ * entirely, importing it throws while the module graph is being INSTANTIATED,
+ * not when the code runs — so every subcommand dies, `--version` included,
+ * before a single line of ours executes. Anything that diagnoses that
+ * situation must therefore sit OUTSIDE the graph it diagnoses: this file is
+ * plain JavaScript, imports nothing, and is loaded before the first `dist/`
+ * module.
+ *
+ * The consequence for the floor number: it is duplicated here, because the
+ * authoritative `NODE_FLOOR` lives behind exactly the import this guard runs
+ * ahead of. `tests/setup/engines-floor.test.ts` holds the two together — the
+ * duplication is deliberate and watched, not an oversight.
+ *
+ * ## The floor comes from a MEASUREMENT that contradicts a declaration
+ *
+ * Anyone changing these numbers needs this, because the obvious source is
+ * wrong. The dependency declares it needs `>= 20.12.0`. It does not: it calls
+ * the formatting helper with an ARRAY of styles, and that overload arrived
+ * later than the helper itself. Measured 2026-08-31 by bisection over nine
+ * installed releases, each confirmed against the real wizard and not only
+ * against the helper:
+ *
+ *   20.12.0  helper present, array form REJECTED  → wizard dies at the first prompt
+ *   20.13.0  array form accepted                  → wizard runs      ← the floor
+ *   21.0.0   helper ABSENT                        → module fails to load
+ *   21.7.3   helper present, array form REJECTED  → wizard dies at the first prompt
+ *   22.0.0   array form accepted                  → wizard runs
+ *
+ * So the supported set is not one interval: the array overload was backported
+ * into the 20 line from 20.13.0, and never into the 21 line at all. 21.7.3 is
+ * the last release that line ever had, so no Node 21 can run this package —
+ * which is why a plain floor comparison is not enough and the 21 line is
+ * refused separately below.
+ *
+ * @license MIT
+ */
+
+/**
+ * Minimum supported Node. Kept equal to `NODE_FLOOR` in
+ * `src/diagnostics/doctor.ts` by `tests/setup/engines-floor.test.ts`.
+ */
+export const NODE_PREFLIGHT_FLOOR = [20, 13, 0];
+
+/**
+ * Major version of the line that never received the backport (see above).
+ *
+ * This is why the guard is STRICTER than the package's own `engines.node`,
+ * which is a plain lower bound and therefore admits this line. npm compares
+ * against that bound, so it prints no `EBADENGINE` warning before installing
+ * here — nothing tells the customer in advance, and this refusal at first
+ * start is the first and only notice they get. Its wording carries that
+ * weight: it has to explain the whole situation on its own.
+ */
+export const UNSUPPORTED_NODE_MAJOR = 21;
+
+/**
+ * Exit codes. Both mean "this interpreter cannot run the package", and they
+ * are distinct so a caller can tell WHICH refusal it hit without parsing
+ * prose. Neither collides with the CLI's generic fatal (99) or with any code
+ * `runCli` returns (0, 1, 2, 130). The values are the conventional
+ * `EX_CONFIG` and `EX_UNAVAILABLE` from sysexits.
+ */
+export const NODE_TOO_OLD_EXIT = 78;
+export const NODE_UNSUPPORTED_LINE_EXIT = 69;
+
+const RESTART_HINT = 'then run the command again. If an AI client starts this server for you,\n'
+    + 'restart that client afterwards so it picks up the newer Node.\n';
+
+/**
+ * The refusal for `versionString`, or `null` when this Node can run the
+ * package.
+ *
+ * Returns the exit code alongside the message so the caller never has to
+ * decide which refusal it is holding.
+ *
+ * Takes the version as an argument rather than reading `process.version` so
+ * the decision is testable on any machine, against any version.
+ *
+ * **An unparseable version is allowed through, deliberately.** Blocking would
+ * turn an unrecognised-but-working runtime into a refusal to start, which is
+ * worse than the confusing loader error the caller would otherwise get: that
+ * error is the behaviour this guard replaces, not one it introduces.
+ */
+export function nodeRuntimeRefusal(versionString, floor = NODE_PREFLIGHT_FLOOR) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(versionString ?? ''));
+    if (m === null) return null;
+
+    const found = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const shown = found.join('.');
+
+    // Checked before the floor: every release of this line is numerically
+    // above the floor and none of them works.
+    if (found[0] === UNSUPPORTED_NODE_MAJOR) {
+        return {
+            exitCode: NODE_UNSUPPORTED_LINE_EXIT,
+            message: `yt-builder-mcp cannot run on the Node.js ${UNSUPPORTED_NODE_MAJOR} line, `
+                + `and this is Node.js ${shown}.\n`
+                + `\n`
+                + `No Node.js ${UNSUPPORTED_NODE_MAJOR} release carries the terminal formatting this package\n`
+                + `needs. Install Node.js ${UNSUPPORTED_NODE_MAJOR + 1} or newer (an LTS release is recommended),\n`
+                + RESTART_HINT,
+        };
+    }
+
+    for (let i = 0; i < 3; i++) {
+        if (found[i] > floor[i]) return null;
+        if (found[i] < floor[i]) {
+            return {
+                exitCode: NODE_TOO_OLD_EXIT,
+                message: `yt-builder-mcp needs Node.js ${floor.join('.')} or newer, but this is Node.js ${shown}.\n`
+                    + `\n`
+                    + `Install Node.js ${floor[0]}.${floor[1]} or newer (an LTS release is recommended),\n`
+                    + RESTART_HINT,
+            };
+        }
+    }
+    return null;
+}

package/bin/yt-builder-mcp.js

@@ -9,11 +9,14 @@
  *                `remove-site` / `set-default` / `test-site` / `help` /
  *                `--help` / `-h` / `--version` / `-v`): forward argv to
  *                `runCli()` in `dist/setup-cli.js` (Wave G.7).
- *   - 'hint'   → no OR unknown subcommand AND stdin is an interactive TTY
+ *   - 'unknown'→ a word was given and it is not one of ours: name it back,
+ *                suggest the likely command, exit 2. Both at a terminal and
+ *                off one — no MCP client passes a word we do not know.
+ *   - 'hint'   → NO subcommand AND stdin is an interactive TTY
  *                (a human ran the bin directly): print a discoverability
  *                hint to stderr and exit 0, instead of silently blocking
  *                on the stdio read loop ("hang").
- *   - 'server' → no OR unknown subcommand AND stdin is NOT a TTY (a real
+ *   - 'server' → NO subcommand AND stdin is NOT a TTY (a real
  *                AI client piping JSON-RPC over stdin): import
  *                `dist/index.js`, which starts the MCP stdio server (or,
  *                under YTB_MCP_TEST_MODE=1, prints the tool list to stderr
@@ -44,20 +47,23 @@
  *
  * @license MIT
  */
-import { argv, stdin, stderr, exit } from 'node:process';
+import { argv, stdin, stderr, exit, version } from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
-import {
+import { nodeRuntimeRefusal } from './node-floor.js';
+
+// Dynamic, not static: a static import is hoisted above everything in this
+// file, so nothing written here could run ahead of it. This is the ONLY
+// `dist/` module loaded before the runtime check below, and it is loaded
+// because the check needs to know the route first.
+const {
     decideInvocation,
     isKnownSubcommand,
     BARE_INVOCATION_HINT,
-} from '../dist/cli/invocation-decision.js';
-import {
-    decideCaReexec,
-    CA_REEXEC_SENTINEL,
-    USE_SYSTEM_CA_FLAG,
-} from '../dist/diagnostics/ca-reexec.js';
+    unknownSubcommandMessage,
+    UNKNOWN_SUBCOMMAND_EXIT_CODE,
+} = await import('../dist/cli/invocation-decision.js');
 
 const args = argv.slice(2);
 const subcommand = args[0];
@@ -75,6 +81,31 @@ if (isKnownSubcommand(subcommand)) {
     action = decideInvocation(subcommand, stdin.isTTY);
 }
 
+// The runtime check applies to the routes a PERSON drives, never to the
+// server. Measured: `dist/index.js` loads on every version from the oldest
+// supported upwards, so the server never needed this floor — only the setup
+// wizard's terminal-formatting dependency does. Refusing the server route
+// would take a working MCP server away from a customer whose only real
+// problem is that `setup` cannot run.
+//
+// The cost of standing here rather than at the top of the file, stated so
+// nobody has to rediscover it: the check is no longer ahead of every `dist/`
+// import. Two are outside it — `invocation-decision.js` above, which must
+// load to decide the route at all, and `index.js` on the server branch,
+// which is deliberately unguarded. Should either ever pull in the wizard's
+// dependency, directly or through one of its own, that import throws while
+// the module graph is instantiated and this check never gets to speak: the
+// customer is back to a message about a missing module export. Both are
+// small and neither imports the wizard today, which is a measurement, not a
+// guarantee.
+if (action !== 'server') {
+    const refusal = nodeRuntimeRefusal(version);
+    if (refusal !== null) {
+        stderr.write(refusal.message);
+        exit(refusal.exitCode);
+    }
+}
+
 if (action === 'cli') {
     try {
         const { runCli } = await import('../dist/setup-cli.js');
@@ -85,6 +116,11 @@ if (action === 'cli') {
         stderr.write(`yt-builder-mcp: fatal: ${msg}\n`);
         exit(99);
     }
+} else if (action === 'unknown') {
+    // A word that is not ours. Said out loud, with a non-zero code — the two
+    // things a customer who mistyped needs and used to get neither of.
+    stderr.write(`${unknownSubcommandMessage(subcommand)}\n`);
+    exit(UNKNOWN_SUBCOMMAND_EXIT_CODE);
 } else if (action === 'hint') {
     stderr.write(`${BARE_INVOCATION_HINT}\n`);
     exit(0);
@@ -99,6 +135,11 @@ if (action === 'cli') {
     // normal in-process start — a re-exec failure must never break startup.
     if (process.env.YTB_MCP_TEST_MODE !== '1') {
         try {
+            const {
+                decideCaReexec,
+                CA_REEXEC_SENTINEL,
+                USE_SYSTEM_CA_FLAG,
+            } = await import('../dist/diagnostics/ca-reexec.js');
             const shouldReexec = decideCaReexec({
                 nodeVersion: process.version,
                 execArgv: process.execArgv,

package/dist/auth.d.ts

@@ -1,148 +1,30 @@
-/**
- * Auth / configuration loading for the MCP server.
- *
- * The MCP server reads two environment variables on startup:
- *
- *   YTB_MCP_SITE_URL      — base URL of the host CMS install (WordPress
- *                           OR Joomla), e.g. `https://example.com`.
- *                           The per-platform REST namespace
- *                           (`/wp-json/yt-builder-mcp/v1` for WP,
- *                           `/api/index.php/v1/yt-builder-mcp` for
- *                           Joomla) is appended internally based on
- *                           runtime platform detection.
- *   YTB_MCP_WP_URL        — DEPRECATED alias for YTB_MCP_SITE_URL,
- *                           kept for back-compat with pre-Wave 7
- *                           configurations. A non-fatal deprecation
- *                           notice is written to stderr when the
- *                           legacy var is used in non-test mode.
- *   YTB_MCP_BEARER_TOKEN  — the Bearer key generated by the plugin
- *                           Settings page (`wp-admin → YT Builder MCP`
- *                           on WordPress, `Components → YT Builder MCP`
- *                           on Joomla).
- *
- * `loadConfig()` throws `ConfigError` if either is missing, so the
- * server fails fast with a useful message rather than emitting cryptic
- * 401/Network errors deep in the request stack.
- *
- * @license MIT
- */
 import { SiteRegistry } from './sites/registry.js';
 export interface ServerConfig {
-    /** Base URL of the host-CMS install (no trailing slash). */
     readonly baseUrl: string;
-    /** Bearer key. */
     readonly bearerToken: string;
-    /** Network timeout (ms) for REST calls. */
     readonly timeoutMs: number;
-    /**
-     * Optional explicit platform hint from {@link ENV_PLATFORM}.
-     * `undefined` lets the consumer rely on URL-shape detection.
-     */
     readonly platformHint?: 'wordpress' | 'joomla';
 }
 export interface LoadConfigOptions {
-    /** Allow the bearer-token to be empty (for health-only smoke tests). */
     readonly allowMissingToken?: boolean;
-    /** Source of env vars (defaults to process.env). */
     readonly env?: NodeJS.ProcessEnv;
 }
-/**
- * Canonical env-var name for the host-CMS base URL (Wave 7+: covers
- * both WordPress and Joomla). Prefer this for all new configurations.
- */
 export declare const ENV_SITE_URL = "YTB_MCP_SITE_URL";
-/**
- * Legacy env-var name kept for back-compat. Pre-Wave-7 configurations
- * (every release through v1.0.x) used `YTB_MCP_WP_URL`. New code should
- * use {@link ENV_SITE_URL}; this constant is retained so the wizard,
- * tests, and error hints can still reference the legacy name.
- */
 export declare const ENV_WP_URL = "YTB_MCP_WP_URL";
 export declare const ENV_BEARER = "YTB_MCP_BEARER_TOKEN";
 export declare const ENV_TIMEOUT = "YTB_MCP_TIMEOUT_MS";
 export declare const ENV_TEST_MODE = "YTB_MCP_TEST_MODE";
-/**
- * U3 — env-var name for a site-level HTTP **Basic-Auth** realm (`user:pass`),
- * distinct from the plugin Bearer. A site fronted by a pure HTTP Basic realm
- * (e.g. `qa.customer.de`) needs `Authorization: Basic …`, which collides with
- * the Bearer on the one `Authorization` header — and `YTB_MCP_EXTRA_HEADERS`
- * forbids an `Authorization` key. This routes the Basic credentials on URL
- * userinfo (`https://user:pass@host`) instead, so the realm gets Basic while
- * the plugin still gets the Bearer. Canonical definition + parser live in
- * `net/site-basic-auth.ts`; re-exported here next to the other `ENV_*` names.
- */
 export { ENV_SITE_BASIC_AUTH } from './net/site-basic-auth.js';
-/**
- * Optional platform hint env var — `'wordpress'` or `'joomla'`. When
- * unset, the server auto-detects from the URL shape (cookbook §3.7.1):
- *   - URL contains `/wp-json/`        → wordpress
- *   - URL contains `/api/index.php/`  → joomla
- *   - origin-only URL                 → defaults to wordpress (back-compat)
- *
- * Set this to `'joomla'` when your YTB_MCP_SITE_URL is an origin-only
- * Joomla URL like `https://example.com/joomla`.
- */
 export declare const ENV_PLATFORM = "YTB_MCP_PLATFORM";
-/**
- * W10 — canonical env-var name for the multi-site registry file. When
- * set, {@link loadRegistry} loads + validates the JSON at this path and
- * the legacy {@link ENV_SITE_URL} / {@link ENV_BEARER} pair is ignored.
- * When unset, the env-bridge falls back to building a one-site registry
- * from the legacy single-site pair.
- */
 export declare const ENV_SITES_FILE = "YTB_MCP_SITES_FILE";
-/**
- * Optional boot-time active-site selector. Names a registry `site_id`
- * that becomes the active (default-target) site the moment the server
- * boots — the YT Builder analogue of api-mapper's `APIMAPPER_PROFILE`.
- *
- * Resolution (see {@link bootstrapActiveSite} in `sites/bootstrap.ts`):
- *   - unset / whitespace / `"default"` → no override; the registry's
- *     own default site applies.
- *   - `"<known site_id>"`              → that site becomes active.
- *   - `"<unknown site_id>"`            → silently ignored (no phantom
- *     switch on a fresh host that inherited the var from elsewhere).
- *
- * The runtime `yootheme_builder_use_site` tool switches it later within
- * a session; this env var only seeds the INITIAL active site so a
- * multi-client config (one MCP entry per client site, each with its own
- * `YTB_MCP_PROFILE`) lands on the right site without a first tool call.
- */
 export declare const ENV_PROFILE = "YTB_MCP_PROFILE";
+export declare function readHostEnv(env: NodeJS.ProcessEnv, key: string): string | undefined;
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare function resolveTimeoutMs(env?: NodeJS.ProcessEnv): number;
 export declare function loadConfig(options?: LoadConfigOptions): ServerConfig;
 export declare function isTestMode(env?: NodeJS.ProcessEnv): boolean;
-/**
- * Options accepted by {@link loadRegistry}.
- */
 export interface LoadRegistryOptions {
-    /** Source of env vars (defaults to process.env). */
     readonly env?: NodeJS.ProcessEnv;
 }
-/**
- * W10 — canonical boot-time registry loader.
- *
- * Resolution order:
- *   1. **Sites file** — if {@link ENV_SITES_FILE} is set to a non-empty
- *      string, parse + validate the JSON at that path and wrap it in a
- *      {@link SiteRegistry}. Schema failures bubble up as
- *      `SitesFileError` (the store does not swallow them); the caller
- *      decides whether to fail-fast or fall back. Wave 10 chooses
- *      fail-fast — explicit file = explicit intent.
- *
- *   2. **Legacy env-bridge** — synthesise a one-site registry from the
- *      pre-W10 single-site env-vars ({@link ENV_SITE_URL} +
- *      {@link ENV_BEARER}, with {@link ENV_PLATFORM} as optional hint).
- *      Preserves the single-site UX for every customer who has not
- *      migrated to a sites.json yet.
- *
- *   3. **Hard fail** — neither configured. Surface a {@link ConfigError}
- *      with the three setup options so the operator knows exactly which
- *      knob to turn.
- *
- * This function replaces {@link loadConfig} on the main boot path.
- * `loadConfig` is intentionally retained for the test-mode fallback in
- * `index.ts` (`--test-mode` smoke probes) and for any embedded consumer
- * that still wants a flat `ServerConfig`.
- */
 export declare function loadRegistry(opts?: LoadRegistryOptions): Promise<SiteRegistry>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD,MAAM,WAAW,YAAY;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CAClD;AAED,MAAM,WAAW,iBAAiB;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAC/C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAC3C,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,eAAO,MAAM,aAAa,sBAAsB,CAAC;AACjD;;;;;;;;;GASG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAC/C;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,uBAAuB,CAAC;AACnD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAkC7C,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,YAAY,CA8ExE;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAExE;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,YAAY,CAC9B,IAAI,GAAE,mBAAwB,GAC/B,OAAO,CAAC,YAAY,CAAC,CA8CvB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD,MAAM,WAAW,YAAY;IAEzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAK3B,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CAClD;AAED,MAAM,WAAW,iBAAiB;IAE9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAErC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACpC;AAMD,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAO/C,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAC3C,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAWjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAW/D,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAQ/C,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAkBnD,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAoB7C,wBAAgB,WAAW,CACvB,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,GAAG,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAIpB;AAED,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAmBzC,wBAAgB,gBAAgB,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACrC,MAAM,CAQR;AAgCD,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,YAAY,CA4ExE;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAExE;AASD,MAAM,WAAW,mBAAmB;IAEhC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACpC;AA4BD,wBAAsB,YAAY,CAC9B,IAAI,GAAE,mBAAwB,GAC/B,OAAO,CAAC,YAAY,CAAC,CA6GvB"}