@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/README.md

@@ -63,18 +63,18 @@ The wizard auto-detects and configures the following clients:
 
 ## Tool surface (gateway model)
 
-The server registers **26 domain tools + 1 gateway = 27 reachable** tools,
-of which **20 are advertised in `tools/list`** (well under Cursor's ~40-tool
+The server registers **29 domain tools + 1 gateway = 30 reachable** tools,
+of which **23 are advertised in `tools/list`** (well under Cursor's ~40-tool
 cap):
 
 - **2 direct top-level tools** (always in `tools/list`):
   `yootheme_builder_health`, `yootheme_builder_diagnose`. The
   "the gateway itself might be broken" escape hatch.
-- **17 essential forwarded tools** (always in `tools/list`): the most-used
-  reads and writes (`pages_list`, `get_etag`, `element_list`, `element_add`,
-  `element_update_settings`, `sources_list`, `element_types_list`,
-  `inspect_multi_items_binding`, and the multi-site `sites_list` / `sites_test`,
-  among others).
+- **20 essential forwarded tools** (always in `tools/list`): the most-used
+  reads and writes (`pages_list`, `pages_create`, `pages_delete`, `get_etag`,
+  `element_list`, `element_add`, `element_update_settings`, `sources_list`,
+  `element_types_list`, `inspect_multi_items_binding`, and the multi-site
+  `sites_list` / `sites_test`, among others).
 - **1 gateway tool** (`yootheme_builder_advanced`): exposes the remaining
   **7 advanced tools** behind a single entry. Call
   `yootheme_builder_advanced({ tool: "<name>" })` for discovery (returns the

package/bin/yt-builder-mcp.js

@@ -2,43 +2,56 @@
 /**
  * Entry point for `npx -y @wootsup/yt-builder-mcp`.
  *
- * Dispatch tree:
- *   - `setup` / `install-skill` / `install` / `--version` / `-v` /
- *     `--help` / `-h` / `help` → forward to `runCli()` in
- *     `dist/setup-cli.js` (Wave G.7).
- *   - no subcommand + interactive TTY → print a discoverability hint
- *     (don't accidentally start MCP server).
- *   - no subcommand + piped stdin/stdout → start the MCP stdio server
- *     (this is what AI clients invoke).
+ * Dispatch tree (the verdict comes from the pure, typed + tested
+ * `decideInvocation()` in `dist/cli/invocation-decision.js`):
+ *   - 'cli'    → known subcommand (`setup` / `install-skill` / `install` /
+ *                `uninstall` / `remove` / `add-site` / `list-sites` /
+ *                `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
+ *                (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
+ *                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
+ *                and exits 0 — the test-mode branch lives in index.ts).
  *
- * The `runCli` / MCP-server split keeps the interactive ergonomics nice
- * while letting AI clients launch the server with zero arguments.
+ * The guard is keyed on `process.stdin.isTTY`: it is `true` only for an
+ * interactive human terminal and `false`/`undefined` for the piped stdin
+ * every MCP client uses, so the client path stays byte-for-byte the same.
+ * YTB_MCP_TEST_MODE=1 forces the 'server' route so the smoke-test probe
+ * always reaches `dist/index.js` even when run from a TTY.
  *
  * @license MIT
  */
-import { argv, stdout, stderr, exit } from 'node:process';
+import { argv, stdin, stderr, exit } from 'node:process';
+
+import {
+    decideInvocation,
+    isKnownSubcommand,
+    BARE_INVOCATION_HINT,
+} from '../dist/cli/invocation-decision.js';
 
 const args = argv.slice(2);
 const subcommand = args[0];
 
-const CLI_SUBCOMMANDS = new Set([
-    'setup',
-    'install-skill',
-    'install',
-    // W9 multi-site CLI subcommands.
-    'add-site',
-    'list-sites',
-    'remove-site',
-    'set-default',
-    'test-site',
-    'help',
-    '--help',
-    '-h',
-    '--version',
-    '-v',
-]);
+// Decide the route. Known subcommands always go to the cli dispatcher.
+// For the bare/unknown path, the smoke-test probe (YTB_MCP_TEST_MODE=1)
+// must always reach dist/index.js — never the interactive hint — so it
+// forces the 'server' route. Otherwise honour the strict-isTTY decision.
+let action;
+if (isKnownSubcommand(subcommand)) {
+    action = 'cli';
+} else if (process.env.YTB_MCP_TEST_MODE === '1') {
+    action = 'server';
+} else {
+    action = decideInvocation(subcommand, stdin.isTTY);
+}
 
-if (subcommand !== undefined && CLI_SUBCOMMANDS.has(subcommand)) {
+if (action === 'cli') {
     try {
         const { runCli } = await import('../dist/setup-cli.js');
         const code = await runCli(args);
@@ -48,18 +61,20 @@ if (subcommand !== undefined && CLI_SUBCOMMANDS.has(subcommand)) {
         stderr.write(`yt-builder-mcp: fatal: ${msg}\n`);
         exit(99);
     }
-} else if (
-    subcommand === undefined &&
-    stdout.isTTY === true &&
-    process.env.YTB_MCP_TEST_MODE !== '1'
-) {
-    stdout.write(
-        'Run `npx -y @wootsup/yt-builder-mcp setup` to configure your AI client.\n',
-    );
-    stdout.write(
-        'Run `npx -y @wootsup/yt-builder-mcp help` for usage.\n',
-    );
+} else if (action === 'hint') {
+    stderr.write(`${BARE_INVOCATION_HINT}\n`);
+    exit(0);
 } else {
-    // Stdin/stdout piped (or YTB_MCP_TEST_MODE=1): MCP stdio mode.
+    // 'server' — stdin is NOT a TTY (an AI client piping JSON-RPC → real
+    // MCP stdio server) or YTB_MCP_TEST_MODE=1 forced this route.
+    // `dist/index.js` branches on the env var: test-mode prints the tool
+    // list to stderr and exits 0; otherwise it starts the stdio server.
+    // Importing here does NOT itself force stdio mode.
+    if (process.env.YTB_MCP_TEST_MODE === '1') {
+        // Deterministic, synchronous marker so the smoke test can confirm
+        // the server route was reached without racing index.js's async
+        // `main()` stdout/stderr flush. Test-mode only — never a real run.
+        stderr.write('[yt-builder-mcp] server-route reached\n');
+    }
     await import('../dist/index.js');
 }

package/dist/auth.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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";
+/**
+ * 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 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

@@ -0,0 +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,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"}

package/dist/auth.js

@@ -0,0 +1,244 @@
+/**
+ * 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 { z } from 'zod';
+import { ConfigError } from './errors.js';
+import { synthesiseFromEnv } from './sites/env-bridge.js';
+import { SiteRegistry } from './sites/registry.js';
+import { SitesFile } from './sites/schema.js';
+import { loadSitesFile } from './sites/store.js';
+/**
+ * Canonical env-var name for the host-CMS base URL (Wave 7+: covers
+ * both WordPress and Joomla). Prefer this for all new configurations.
+ */
+export 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 const ENV_WP_URL = 'YTB_MCP_WP_URL';
+export const ENV_BEARER = 'YTB_MCP_BEARER_TOKEN';
+export const ENV_TIMEOUT = 'YTB_MCP_TIMEOUT_MS';
+export const ENV_TEST_MODE = 'YTB_MCP_TEST_MODE';
+/**
+ * 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 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 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 const ENV_PROFILE = 'YTB_MCP_PROFILE';
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Maximum accepted length for a Bearer token (defense-in-depth bound;
+ * the real plugin keys are ~150-300 bytes, the 512 ceiling protects
+ * against accidental file-pastes / log dumps / memory abuse).
+ */
+const BEARER_MAX_LEN = 512;
+/**
+ * Bearer-token format check — matches the plugin's `KeyService.php`
+ * `PREFIX = ytb_live_` (and the planned `ytb_test_` future variant).
+ * Token shape: `ytb_(live|test)_<payloadB64Url>.<sigB64Url>` where
+ * base64url uses `[A-Za-z0-9_-]` (no dots inside the payload or sig).
+ *
+ * Round-1 audit I7 fix (2026-05-22): the earlier `.trim()` + empty-check
+ * was not enough to catch the most common config mistakes — the leading
+ * `Bearer ` prefix accidentally pasted into the env var, copy-paste
+ * truncation (no `.` separator), or a totally wrong token style. We
+ * fail-fast here so the client never sends a known-bad value upstream.
+ */
+const BEARER_FORMAT_SCHEMA = z
+    .string()
+    .max(BEARER_MAX_LEN, `Bearer too long (max ${String(BEARER_MAX_LEN)} chars). The env var YTB_MCP_BEARER_TOKEN seems to contain something other than a plain key — strip leading "Bearer " or paste only the key copied from wp-admin → "YT Builder MCP" → Settings.`)
+    .regex(/^ytb_(live|test)_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/, 'Bearer must match ytb_(live|test)_<payloadB64Url>.<sigB64Url> format (copy the key as shown in wp-admin → "YT Builder MCP" → Settings; do NOT prepend "Bearer ").');
+export function loadConfig(options = {}) {
+    const env = options.env ?? process.env;
+    // Wave 7: YTB_MCP_SITE_URL is canonical (covers both WP + Joomla);
+    // YTB_MCP_WP_URL is retained as a deprecated back-compat alias.
+    // Resolution order: SITE_URL wins; legacy WP_URL fallback emits a
+    // soft deprecation note in non-test mode.
+    const rawSiteUrl = (env[ENV_SITE_URL] ?? '').trim();
+    const rawLegacyUrl = (env[ENV_WP_URL] ?? '').trim();
+    const rawUrl = rawSiteUrl !== '' ? rawSiteUrl : rawLegacyUrl;
+    // Soft deprecation notice — only when the loader is being used in
+    // its real-server role (env defaulted to process.env). Programmatic
+    // callers (tests, embedded uses) pass `options.env` explicitly and
+    // are silently treated as opt-in to the legacy var.
+    if (rawSiteUrl === ''
+        && rawLegacyUrl !== ''
+        && options.env === undefined
+        && !isTestMode(env)) {
+        process.stderr.write(`[yt-builder-mcp] notice: ${ENV_WP_URL} is deprecated — ` +
+            `set ${ENV_SITE_URL} instead (same value; covers WordPress + Joomla).\n`);
+    }
+    const rawToken = (env[ENV_BEARER] ?? '').trim();
+    const rawTimeout = (env[ENV_TIMEOUT] ?? '').trim();
+    if (rawUrl === '') {
+        throw new ConfigError(`Missing ${ENV_SITE_URL}. Set it to your CMS base URL ` +
+            '(e.g. https://example.com — WordPress or Joomla). ' +
+            'Run `yt-builder-mcp setup` to configure.');
+    }
+    if (!options.allowMissingToken && rawToken === '') {
+        throw new ConfigError(`Missing ${ENV_BEARER}. Generate a Bearer key in wp-admin → "YT Builder MCP" → ` +
+            'Settings, then run `yt-builder-mcp setup`.');
+    }
+    // I7-fix: enforce the Bearer-format contract before the client
+    // makes any request. Empty token is allowed only via
+    // `allowMissingToken` (the health-only smoke path); any other
+    // non-empty value MUST match the plugin's KeyService format.
+    if (rawToken !== '') {
+        const parsed = BEARER_FORMAT_SCHEMA.safeParse(rawToken);
+        if (!parsed.success) {
+            const issueMsg = parsed.error.issues
+                .map((iss) => iss.message)
+                .join(' ');
+            throw new ConfigError(`Invalid ${ENV_BEARER}: ${issueMsg}`);
+        }
+    }
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    if (rawTimeout !== '') {
+        const parsed = Number.parseInt(rawTimeout, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            timeoutMs = parsed;
+        }
+    }
+    const rawPlatform = (env[ENV_PLATFORM] ?? '').trim().toLowerCase();
+    const platformHint = rawPlatform === 'wordpress' || rawPlatform === 'joomla'
+        ? rawPlatform
+        : undefined;
+    return {
+        baseUrl: stripTrailingSlash(rawUrl),
+        bearerToken: rawToken,
+        timeoutMs,
+        ...(platformHint !== undefined ? { platformHint } : {}),
+    };
+}
+export function isTestMode(env = process.env) {
+    return (env[ENV_TEST_MODE] ?? '') === '1';
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+/**
+ * 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 async function loadRegistry(opts = {}) {
+    const env = opts.env ?? process.env;
+    // (1) sites file (preferred).
+    const sitesFilePath = (env[ENV_SITES_FILE] ?? '').trim();
+    if (sitesFilePath !== '') {
+        // loadSitesFile handles both "file present" and "file absent"
+        // (the latter returns an emptySitesFile). When the file is
+        // empty (no sites), fall through to env-bridge instead of
+        // booting with an empty registry — operators who set
+        // SITES_FILE to a not-yet-populated path should still get the
+        // legacy env-var ramp until they run `add-site`.
+        const file = await loadSitesFile(sitesFilePath);
+        if (file.sites.length > 0) {
+            return new SiteRegistry(file);
+        }
+    }
+    // (2) legacy env-bridge. The bridge already enforces URL/bearer
+    // non-emptiness and platform-hint validity, but we re-validate the
+    // full file shape through the W1 Zod schema before handing it to
+    // the registry. Defense-in-depth: a future env-bridge change cannot
+    // introduce a SitesFileT-shape regression that lands on the
+    // registry path without first failing this gate.
+    const synth = synthesiseFromEnv(env);
+    if (synth !== null) {
+        const parsed = SitesFile.safeParse(synth);
+        if (!parsed.success) {
+            const issues = parsed.error.issues
+                .map((i) => `${i.path.join('.')}: ${i.message}`)
+                .join('; ');
+            throw new ConfigError(`Env-bridge synthesised an invalid sites file: ${issues}`);
+        }
+        return new SiteRegistry(parsed.data);
+    }
+    // (3) fail-fast.
+    throw new ConfigError('No sites configured. Either: '
+        + '(a) set YTB_MCP_SITES_FILE to your sites.json path, or '
+        + '(b) set YTB_MCP_SITE_URL + YTB_MCP_BEARER_TOKEN for '
+        + 'single-site mode, or '
+        + '(c) run `npx -y @wootsup/yt-builder-mcp setup` interactively.');
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/cli/invocation-decision.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure decision core for the `bin/yt-builder-mcp.js` dispatcher.
+ *
+ * The bin is a thin JS shim (not type-checked, not linted) so the
+ * branching logic that decides what a given invocation should DO lives
+ * here, in a typed + tested + covered module. The shim imports the
+ * compiled `dist/cli/invocation-decision.js` and acts on the verdict.
+ *
+ * Three outcomes:
+ *   - 'cli'    → a known subcommand (setup / uninstall / add-site / …):
+ *                forward argv to the setup-cli dispatcher.
+ *   - 'hint'   → no or unknown subcommand AND stdin is an interactive
+ *                TTY (a human ran the bin directly): print the
+ *                discoverability hint to stderr and exit 0, rather than
+ *                silently blocking on the stdio read loop ("hang").
+ *   - 'server' → no or unknown subcommand AND stdin is NOT a TTY (a real
+ *                MCP client piping JSON-RPC over stdin): boot the stdio
+ *                server. This path MUST stay byte-for-byte equivalent to
+ *                the pre-hint behaviour — the guard is strict on isTTY so
+ *                the client path is never diverted.
+ *
+ * @license MIT
+ */
+/**
+ * Canonical set of subcommands handled by the setup-cli dispatcher.
+ *
+ * Mirrors `CLI_SUBCOMMANDS` in `bin/yt-builder-mcp.js`. Kept frozen so a
+ * consumer cannot mutate the shared decision surface at runtime.
+ */
+export declare const KNOWN_SUBCOMMANDS: ReadonlySet<string>;
+/**
+ * Discoverability hint printed to stderr when a human runs the bin
+ * directly (no/unknown subcommand at an interactive TTY). stderr, not
+ * stdout, so it never contaminates a JSON-RPC frame if redirected.
+ */
+export declare const BARE_INVOCATION_HINT: string;
+/** What the bin should do for a given invocation. */
+export type InvocationAction = 'cli' | 'hint' | 'server';
+/**
+ * True when `sub` is a subcommand the setup-cli dispatcher handles.
+ * `undefined` (no argument) is never a known subcommand.
+ */
+export declare function isKnownSubcommand(sub: string | undefined): boolean;
+/**
+ * Decide the bin action from the first CLI argument and whether stdin is
+ * an interactive TTY.
+ *
+ * @param subcommand  argv[2], or undefined when no argument was passed.
+ * @param stdinIsTTY  `process.stdin.isTTY` — `true` only for an
+ *                    interactive human terminal; `false`/`undefined` for
+ *                    a piped stream (which is how every MCP client runs
+ *                    the server). The guard is STRICT: only `=== true`
+ *                    yields the hint, so the MCP-client path is never
+ *                    diverted.
+ */
+export declare function decideInvocation(subcommand: string | undefined, stdinIsTTY: boolean | undefined): InvocationAction;
+//# sourceMappingURL=invocation-decision.d.ts.map

package/dist/cli/invocation-decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-decision.d.ts","sourceRoot":"","sources":["../../src/cli/invocation-decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAoBjD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAKxB,CAAC;AAEZ,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAElE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC5B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,OAAO,GAAG,SAAS,GAChC,gBAAgB,CAMlB"}