@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/dist/sites/client-pool.js

@@ -0,0 +1,222 @@
+/**
+ * W4 — ClientPool: caches one {@link RestClient} per `site_id`.
+ *
+ * The pool sits between the W3 {@link SiteRegistry} (which maps a
+ * `site_id` → entry + memoised {@link Platform}) and the W2
+ * {@link SecretResolver} (which produces a bearer token at call time)
+ * and emits {@link PoolResolution} bundles ready for tool handlers.
+ *
+ * Design choices (per plan §W4, Z.562-644):
+ *
+ *  - **One client per site_id.** The first `resolve(id)` runs bearer +
+ *    platform resolve in parallel via `Promise.all` (saves one
+ *    round-trip-time per cold site) and stores the constructed
+ *    `RestClient`. All subsequent calls reuse the same instance —
+ *    identity-equal across the process lifetime.
+ *
+ *  - **Cold parallel calls are racey-but-safe.** When N callers arrive
+ *    for the same uncached site_id simultaneously, the plan §W4
+ *    explicitly accepts N first-time `secretResolver.resolve()` calls
+ *    (Z.630): `op read` is idempotent + latency dominates so a
+ *    hard-once Promise-cache would not materially help. The W3
+ *    registry's Promise-cache handles the platform side. The last
+ *    setter wins the `cache.set(id, client)` race; subsequent
+ *    `resolve()` calls see a stable single instance. Identity is
+ *    eventual, not instantaneous — but stable from call N+1 onwards.
+ *
+ *  - **`invalidate(siteId)` for post-401 force-re-resolve.** When the
+ *    auth layer detects a `401 invalid_kid`, it can drop the cached
+ *    client so the next call re-fetches the bearer through `op` and
+ *    constructs a fresh `RestClient`.
+ *
+ *  - **Structured errors.** `NoDefaultSiteError` and `UnknownSiteError`
+ *    carry `code` + (for unknown) `siteId` + `available[]` so the
+ *    auth/tool layer can branch on `error.code` instead of substring
+ *    matching the message.
+ *
+ * @license MIT
+ */
+import { RestClient } from '../client.js';
+/**
+ * Thrown when `resolve()` is called without a `siteId` AND the
+ * registry has no default configured (neither `default_site_id` nor a
+ * flagged `is_default:true` entry). The auth layer surfaces this as a
+ * `no_default_site` MCP error with a hint to run
+ * `npx -y @wootsup/yt-builder-mcp add-site --default`.
+ */
+export class NoDefaultSiteError extends Error {
+    code = 'no_default_site';
+    constructor(message = 'No site_id supplied and no default site is configured. '
+        + 'Add a site via `npx -y @wootsup/yt-builder-mcp add-site --default --url ... --token ...` '
+        + 'or pass site_id explicitly. Use yootheme_builder_sites_list to discover IDs.') {
+        super(message);
+        this.name = 'NoDefaultSiteError';
+    }
+}
+/**
+ * Thrown when `resolve('some-id')` cannot find `some-id` in the
+ * registry. Carries the requested `siteId` and the (insertion-order)
+ * list of configured ids so the caller can render a friendly
+ * "did-you-mean" hint.
+ */
+export class UnknownSiteError extends Error {
+    siteId;
+    available;
+    code = 'unknown_site';
+    constructor(siteId, available) {
+        super(`Site "${siteId}" not found. Available: `
+            + (available.length > 0 ? available.join(', ') : '(none configured)'));
+        this.siteId = siteId;
+        this.available = available;
+        this.name = 'UnknownSiteError';
+    }
+}
+/**
+ * Process-local cache of {@link RestClient} instances keyed by
+ * `site_id`. Constructed once at server boot (W6) and shared across
+ * all tool handlers.
+ *
+ * The pool is NOT thread-safe in the strict sense (Node is
+ * single-threaded but `await` can interleave); the cold-parallel-call
+ * behaviour is documented at the top of this file.
+ */
+export class ClientPool {
+    _registry;
+    secretResolver;
+    timeoutMs;
+    cache = new Map();
+    /**
+     * Runtime active-site override (Phase 3 — `yootheme_builder_use_site`).
+     *
+     * The {@link SiteRegistry} is immutable: its `defaultSiteId()` is
+     * fixed for the process lifetime. api-mapper's parallel feature
+     * (`apimapper_use_profile`) moves a mutable active-pointer in its
+     * on-disk ProfileStore. YT Builder instead keeps the registry
+     * read-only and layers a process-local override HERE: when set,
+     * `resolve(undefined)` targets this id BEFORE consulting
+     * `registry.defaultSiteId()`. An explicit `site_id` argument to
+     * `resolve()` always wins over the override.
+     *
+     * `null` = no override (registry default in effect).
+     */
+    activeOverride = null;
+    constructor(_registry, secretResolver, timeoutMs = 15_000) {
+        this._registry = _registry;
+        this.secretResolver = secretResolver;
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * The current runtime active-site override, or `null` when none is
+     * set (the registry default is in effect). Read-only peek — does not
+     * resolve a client or hit the network.
+     */
+    activeSiteId() {
+        return this.activeOverride;
+    }
+    /**
+     * Set (or clear) the runtime active-site override.
+     *
+     * Passing a `site_id` makes every subsequent `resolve(undefined)`
+     * target that site. Passing `null` clears the override so the
+     * registry default applies again.
+     *
+     * @throws {UnknownSiteError} when `siteId` is not in the registry —
+     *   the pointer is left UNCHANGED on a bad switch so a typo never
+     *   silently strands the session on a non-existent site.
+     */
+    setActiveSite(siteId) {
+        if (siteId === null) {
+            this.activeOverride = null;
+            return;
+        }
+        if (this.registry.get(siteId) === null) {
+            throw new UnknownSiteError(siteId, this.registry.listIds());
+        }
+        this.activeOverride = siteId;
+    }
+    /**
+     * Read-only accessor for the underlying {@link SiteRegistry}. Used
+     * internally by the W7 `buildSitesTools(pool)` aggregator so the
+     * `sites_list` tool can render the configured-sites table without
+     * requiring callers to thread the registry separately. The registry
+     * itself is immutable from the outside (no mutator surface) so
+     * exposing it here is safe — `listForDisplay()` / `defaultSiteId()` /
+     * `listIds()` are all read-only operations.
+     *
+     * @internal Internal accessor for buildSitesTools; do not consume
+     * from tool handlers. Handlers should call `pool.resolve(siteId)`
+     * to get a `{client, site}` bundle instead.
+     */
+    get registry() {
+        return this._registry;
+    }
+    /**
+     * Resolve a site_id to its cached {@link RestClient} + descriptor.
+     *
+     * @param siteId Explicit site_id from the tool param. When
+     *   `undefined`, the registry's `defaultSiteId()` is used.
+     * @throws {NoDefaultSiteError} when `siteId` is omitted and no
+     *   default is configured.
+     * @throws {UnknownSiteError} when the resolved id is not in the
+     *   registry (either the explicit id is wrong, or the registry's
+     *   `default_site_id` points at a stale entry).
+     */
+    async resolve(siteId) {
+        // Resolution order (Phase 3):
+        //   1. explicit `siteId` arg (always wins)
+        //   2. runtime active-site override (`setActiveSite`)
+        //   3. registry default (`defaultSiteId()`)
+        const id = siteId
+            ?? this.activeOverride
+            ?? this.registry.defaultSiteId();
+        if (id === null) {
+            throw new NoDefaultSiteError();
+        }
+        const entry = this.registry.get(id);
+        if (entry === null) {
+            throw new UnknownSiteError(id, this.registry.listIds());
+        }
+        let client = this.cache.get(id);
+        if (client === undefined) {
+            // Plan §W4 Z.604-608: parallelise bearer + platform on a
+            // cold call. The W3 registry's Promise-cache de-dupes the
+            // platform probe across N parallel callers; the bearer
+            // side is allowed N first-time calls (op read idempotent).
+            const [bearer, platform] = await Promise.all([
+                this.secretResolver.resolve(entry),
+                this.registry.platformFor(id),
+            ]);
+            client = new RestClient({
+                platform,
+                bearerToken: bearer.token,
+                timeoutMs: this.timeoutMs,
+            });
+            this.cache.set(id, client);
+        }
+        // `platformFor` is memoised in the registry; calling it a
+        // second time here is a O(1) Promise.resolve from the W3
+        // Promise-cache, NOT a fresh probe. Keeps the `ResolvedSite`
+        // synthesis self-contained even when the client was warm.
+        const platform = await this.registry.platformFor(id);
+        const resolved = {
+            id,
+            url: entry.url,
+            platform,
+            isDefault: entry.is_default,
+            bearerSource: entry.bearer_ref !== undefined ? 'op' : 'plain',
+            ...(entry.label !== undefined ? { label: entry.label } : {}),
+        };
+        return { client, site: resolved };
+    }
+    /**
+     * Drop the cached client for `siteId` — used by the auth layer
+     * after a `401 invalid_kid` so the next call re-runs the bearer
+     * resolve and builds a fresh {@link RestClient}.
+     *
+     * No-op when `siteId` is not in the cache.
+     */
+    invalidate(siteId) {
+        this.cache.delete(siteId);
+    }
+}
+//# sourceMappingURL=client-pool.js.map

package/dist/sites/client-pool.js.map

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

package/dist/sites/env-bridge.d.ts

@@ -0,0 +1,55 @@
+/**
+ * W3 — Env-Bridge: synthesise a one-site {@link SitesFileT} from the
+ * legacy single-site env-vars when no `sites.json` exists on disk.
+ *
+ * Why: pre-multi-site customers configured the MCP server via
+ * `YTB_MCP_SITE_URL` (or the older `YTB_MCP_WP_URL`) + `YTB_MCP_BEARER_TOKEN`.
+ * Multi-site infra must NEVER break that experience. When no
+ * `sites.json` is found, the boot path consults this bridge; if both
+ * required env-vars are present we materialise an in-memory one-site
+ * file with `site_id: 'default'` and `is_default: true`. The rest of
+ * the system (registry, resolver, tool builder) then operates on
+ * `SitesFileT` uniformly — there is no second code path for the
+ * legacy single-site case.
+ *
+ * Returns `null` when either required env-var is missing or empty so
+ * the caller can fall through to "no sites configured" UX.
+ *
+ * W12-R1.1 consolidation:
+ *   - Env-var names are imported from `../auth.js` (single source of
+ *     truth) instead of duplicated as string-literals.
+ *   - Raw URL + bearer are `.trim()`ed; whitespace-only values are
+ *     treated as missing (return null), matching `loadConfig` behaviour.
+ *   - Unknown `YTB_MCP_PLATFORM` values throw `ConfigError` so a typo
+ *     (`woodpress`, `joomlaa`) surfaces immediately instead of silently
+ *     downgrading to `'auto'` and confusing the runtime probe.
+ *
+ * @license MIT
+ */
+import type { SitesFileT } from './schema.js';
+/**
+ * Trim exactly one trailing `/` from a string. `""` stays `""`. A
+ * string with two trailing slashes keeps the inner one (`"a//"` →
+ * `"a/"`), preserving the operator's apparent intent — single-slash
+ * normalisation is a paste-error fix, not an aggressive cleanup.
+ */
+export declare function stripTrailingSlash(s: string): string;
+/**
+ * Build a one-site {@link SitesFileT} from `env`, or return `null` if
+ * neither URL nor bearer is configured. Order of URL precedence:
+ *   1. {@link ENV_SITE_URL} (new, multi-site-aware name)
+ *   2. {@link ENV_WP_URL}   (legacy single-site name, still honoured)
+ *
+ * The platform hint comes from {@link ENV_PLATFORM} when set to
+ * `wordpress` / `joomla` / `auto`. An empty / unset value falls back to
+ * `'auto'` so the runtime probe (see `platformForUrlAsync`) decides.
+ * Any OTHER non-empty value throws `ConfigError` — a typo like
+ * `woodpress` is loud-failed at boot rather than silently degraded.
+ *
+ * Note: this function does NOT validate the URL or bearer-token shape
+ * beyond non-empty trimming — the W1 {@link SitesFile} schema does that
+ * the moment the caller hands the synthesised file to a registry
+ * constructor.
+ */
+export declare function synthesiseFromEnv(env: NodeJS.ProcessEnv): SitesFileT | null;
+//# sourceMappingURL=env-bridge.d.ts.map

package/dist/sites/env-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-bridge.d.ts","sourceRoot":"","sources":["../../src/sites/env-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAUH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,GACvB,UAAU,GAAG,IAAI,CAqCnB"}

package/dist/sites/env-bridge.js

@@ -0,0 +1,94 @@
+/**
+ * W3 — Env-Bridge: synthesise a one-site {@link SitesFileT} from the
+ * legacy single-site env-vars when no `sites.json` exists on disk.
+ *
+ * Why: pre-multi-site customers configured the MCP server via
+ * `YTB_MCP_SITE_URL` (or the older `YTB_MCP_WP_URL`) + `YTB_MCP_BEARER_TOKEN`.
+ * Multi-site infra must NEVER break that experience. When no
+ * `sites.json` is found, the boot path consults this bridge; if both
+ * required env-vars are present we materialise an in-memory one-site
+ * file with `site_id: 'default'` and `is_default: true`. The rest of
+ * the system (registry, resolver, tool builder) then operates on
+ * `SitesFileT` uniformly — there is no second code path for the
+ * legacy single-site case.
+ *
+ * Returns `null` when either required env-var is missing or empty so
+ * the caller can fall through to "no sites configured" UX.
+ *
+ * W12-R1.1 consolidation:
+ *   - Env-var names are imported from `../auth.js` (single source of
+ *     truth) instead of duplicated as string-literals.
+ *   - Raw URL + bearer are `.trim()`ed; whitespace-only values are
+ *     treated as missing (return null), matching `loadConfig` behaviour.
+ *   - Unknown `YTB_MCP_PLATFORM` values throw `ConfigError` so a typo
+ *     (`woodpress`, `joomlaa`) surfaces immediately instead of silently
+ *     downgrading to `'auto'` and confusing the runtime probe.
+ *
+ * @license MIT
+ */
+import { ENV_BEARER, ENV_PLATFORM, ENV_SITE_URL, ENV_WP_URL, } from '../auth.js';
+import { ConfigError } from '../errors.js';
+/**
+ * Trim exactly one trailing `/` from a string. `""` stays `""`. A
+ * string with two trailing slashes keeps the inner one (`"a//"` →
+ * `"a/"`), preserving the operator's apparent intent — single-slash
+ * normalisation is a paste-error fix, not an aggressive cleanup.
+ */
+export function stripTrailingSlash(s) {
+    if (s.length === 0)
+        return s;
+    return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+/**
+ * Build a one-site {@link SitesFileT} from `env`, or return `null` if
+ * neither URL nor bearer is configured. Order of URL precedence:
+ *   1. {@link ENV_SITE_URL} (new, multi-site-aware name)
+ *   2. {@link ENV_WP_URL}   (legacy single-site name, still honoured)
+ *
+ * The platform hint comes from {@link ENV_PLATFORM} when set to
+ * `wordpress` / `joomla` / `auto`. An empty / unset value falls back to
+ * `'auto'` so the runtime probe (see `platformForUrlAsync`) decides.
+ * Any OTHER non-empty value throws `ConfigError` — a typo like
+ * `woodpress` is loud-failed at boot rather than silently degraded.
+ *
+ * Note: this function does NOT validate the URL or bearer-token shape
+ * beyond non-empty trimming — the W1 {@link SitesFile} schema does that
+ * the moment the caller hands the synthesised file to a registry
+ * constructor.
+ */
+export function synthesiseFromEnv(env) {
+    const rawUrl = (env[ENV_SITE_URL] ?? env[ENV_WP_URL] ?? '').trim();
+    const bearer = (env[ENV_BEARER] ?? '').trim();
+    if (rawUrl === '' || bearer === '')
+        return null;
+    const rawPlatform = env[ENV_PLATFORM];
+    const platformHint = rawPlatform === undefined ? '' : rawPlatform.trim();
+    let platform;
+    if (platformHint === '') {
+        platform = 'auto';
+    }
+    else if (platformHint === 'wordpress'
+        || platformHint === 'joomla'
+        || platformHint === 'auto') {
+        platform = platformHint;
+    }
+    else {
+        throw new ConfigError(`Invalid ${ENV_PLATFORM}: "${platformHint}". `
+            + 'Must be one of: wordpress, joomla, auto (or unset for auto-detect).');
+    }
+    return {
+        schema_version: 1,
+        default_site_id: 'default',
+        sites: [
+            {
+                site_id: 'default',
+                url: stripTrailingSlash(rawUrl),
+                platform,
+                bearer,
+                is_default: true,
+                label: 'Default site (env)',
+            },
+        ],
+    };
+}
+//# sourceMappingURL=env-bridge.js.map

package/dist/sites/env-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-bridge.js","sourceRoot":"","sources":["../../src/sites/env-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACH,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAI3C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAS;IACxC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7B,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAC7B,GAAsB;IAEtB,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,WAAW,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IACzE,IAAI,QAAyC,CAAC;IAC9C,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;QACtB,QAAQ,GAAG,MAAM,CAAC;IACtB,CAAC;SAAM,IACH,YAAY,KAAK,WAAW;WACzB,YAAY,KAAK,QAAQ;WACzB,YAAY,KAAK,MAAM,EAC5B,CAAC;QACC,QAAQ,GAAG,YAAY,CAAC;IAC5B,CAAC;SAAM,CAAC;QACJ,MAAM,IAAI,WAAW,CACjB,WAAW,YAAY,MAAM,YAAY,KAAK;cAC5C,qEAAqE,CAC1E,CAAC;IACN,CAAC;IAED,OAAO;QACH,cAAc,EAAE,CAAC;QACjB,eAAe,EAAE,SAAS;QAC1B,KAAK,EAAE;YACH;gBACI,OAAO,EAAE,SAAS;gBAClB,GAAG,EAAE,kBAAkB,CAAC,MAAM,CAAC;gBAC/B,QAAQ;gBACR,MAAM;gBACN,UAAU,EAAE,IAAI;gBAChB,KAAK,EAAE,oBAAoB;aAC9B;SACJ;KACJ,CAAC;AACN,CAAC"}

package/dist/sites/paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * W1 — Sites-Storage Foundation: default on-disk path resolver.
+ *
+ * Resolution order:
+ *  1. `$XDG_CONFIG_HOME/yt-builder-mcp/sites.json` (XDG Base-Dir spec)
+ *  2. `$HOME/.config/yt-builder-mcp/sites.json` (XDG fallback)
+ *  3. `os.tmpdir()/yt-builder-mcp/sites.json` + stderr warning (last
+ *     resort — used in CI / containers where HOME may be unset).
+ *
+ * The W2/W3 layer never touches paths directly — callers ask this module
+ * for the canonical location and pass the resolved string to the store.
+ *
+ * @license MIT
+ */
+/**
+ * Pure environment lookup so tests can inject a process-env-like object
+ * without mutating `process.env`. Returns the path that the load/save
+ * layer should target.
+ */
+export declare function defaultSitesFilePath(env?: NodeJS.ProcessEnv, log?: (msg: string) => void): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/sites/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/sites/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAqD,GAC5E,MAAM,CAgBR"}

package/dist/sites/paths.js

@@ -0,0 +1,37 @@
+/**
+ * W1 — Sites-Storage Foundation: default on-disk path resolver.
+ *
+ * Resolution order:
+ *  1. `$XDG_CONFIG_HOME/yt-builder-mcp/sites.json` (XDG Base-Dir spec)
+ *  2. `$HOME/.config/yt-builder-mcp/sites.json` (XDG fallback)
+ *  3. `os.tmpdir()/yt-builder-mcp/sites.json` + stderr warning (last
+ *     resort — used in CI / containers where HOME may be unset).
+ *
+ * The W2/W3 layer never touches paths directly — callers ask this module
+ * for the canonical location and pass the resolved string to the store.
+ *
+ * @license MIT
+ */
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Pure environment lookup so tests can inject a process-env-like object
+ * without mutating `process.env`. Returns the path that the load/save
+ * layer should target.
+ */
+export function defaultSitesFilePath(env = process.env, log = (msg) => { process.stderr.write(msg + '\n'); }) {
+    const xdg = env.XDG_CONFIG_HOME;
+    if (xdg !== undefined && xdg.length > 0) {
+        return join(xdg, 'yt-builder-mcp', 'sites.json');
+    }
+    const home = env.HOME;
+    if (home !== undefined && home.length > 0) {
+        return join(home, '.config', 'yt-builder-mcp', 'sites.json');
+    }
+    const tmp = tmpdir();
+    log(`[yt-builder-mcp] WARN: neither XDG_CONFIG_HOME nor HOME is set — ` +
+        `sites file will be stored in ${tmp}/yt-builder-mcp/sites.json. ` +
+        `This is ephemeral; set HOME or XDG_CONFIG_HOME for persistence.`);
+    return join(tmp, 'yt-builder-mcp', 'sites.json');
+}
+//# sourceMappingURL=paths.js.map

package/dist/sites/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/sites/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAChC,MAAyB,OAAO,CAAC,GAAG,EACpC,MAA6B,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAE3E,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC;IAChC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,GAAG,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,GAAG,CACC,mEAAmE;QACnE,gCAAgC,GAAG,8BAA8B;QACjE,iEAAiE,CACpE,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAC;AACrD,CAAC"}

package/dist/sites/probe.d.ts

@@ -0,0 +1,60 @@
+/**
+ * W12-R1.2 — shared site-probe helper.
+ *
+ * Both `sites/tools/sites-test.ts` (MCP tool surface) AND
+ * `sites/cli/test-site.ts` (CLI surface) need to run the same
+ * `/health` (no auth) + `/etag` (auth) parallel probe and classify
+ * the outcome into a `{plugin_reachable, bearer_valid, etag_received,
+ * summary}` shape. Pre-W12 the two call sites duplicated the
+ * Promise.allSettled + RestError branching twice (~40 LoC drift
+ * surface).
+ *
+ * This module is the single source of truth for that probe. The two
+ * call sites map the result into their respective output envelopes
+ * (toolkit detail-result for MCP, plain text lines for CLI) but never
+ * re-implement the probe-routing logic.
+ *
+ * Failure-mode mapping (audit-aligned):
+ *   - /health rejects, /etag rejects   → plugin unreachable
+ *   - /health rejects, /etag 401/403   → plugin reachable (etag replied),
+ *                                        bearer rejected
+ *   - /health rejects, /etag other     → plugin unreachable
+ *                                        (bearer_error still surfaced)
+ *   - /health ok,      /etag rejects   → plugin reachable, bearer rejected
+ *   - /health ok,      /etag ok        → green
+ *
+ * Never throws on probe failure — those land in the result fields.
+ * Throws only on truly unexpected programmer errors (e.g. the client
+ * arg is not a RestClient).
+ *
+ * @license MIT
+ */
+import type { RestClient } from '../client.js';
+/**
+ * Probe outcome shape consumed by both the MCP tool and the CLI. Optional
+ * HTTP status codes are surfaced when the probe yielded a `RestError`
+ * (helpful for operators triaging 401 vs 404 vs 500).
+ */
+export interface ProbeResult {
+    readonly plugin_reachable: boolean;
+    readonly bearer_valid: boolean;
+    readonly etag_received: boolean;
+    readonly summary: string;
+    readonly plugin_error?: string;
+    readonly bearer_error?: string;
+    readonly http_status_health?: number;
+    readonly http_status_etag?: number;
+}
+/**
+ * Run the canonical `/health` + `/etag` parallel probe against a
+ * site-bound {@link RestClient}.
+ *
+ * `Promise.allSettled` so a thrown probe never short-circuits the
+ * other — both legs always contribute to the final classification.
+ *
+ * The summary string is deterministic per `{plugin_reachable, bearer_valid}`
+ * combination so customer-facing UX (CLI table, MCP detail-card) is
+ * identical across the two surfaces.
+ */
+export declare function probeSite(client: RestClient): Promise<ProbeResult>;
+//# sourceMappingURL=probe.d.ts.map

package/dist/sites/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../src/sites/probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAkExE"}

package/dist/sites/probe.js

@@ -0,0 +1,112 @@
+/**
+ * W12-R1.2 — shared site-probe helper.
+ *
+ * Both `sites/tools/sites-test.ts` (MCP tool surface) AND
+ * `sites/cli/test-site.ts` (CLI surface) need to run the same
+ * `/health` (no auth) + `/etag` (auth) parallel probe and classify
+ * the outcome into a `{plugin_reachable, bearer_valid, etag_received,
+ * summary}` shape. Pre-W12 the two call sites duplicated the
+ * Promise.allSettled + RestError branching twice (~40 LoC drift
+ * surface).
+ *
+ * This module is the single source of truth for that probe. The two
+ * call sites map the result into their respective output envelopes
+ * (toolkit detail-result for MCP, plain text lines for CLI) but never
+ * re-implement the probe-routing logic.
+ *
+ * Failure-mode mapping (audit-aligned):
+ *   - /health rejects, /etag rejects   → plugin unreachable
+ *   - /health rejects, /etag 401/403   → plugin reachable (etag replied),
+ *                                        bearer rejected
+ *   - /health rejects, /etag other     → plugin unreachable
+ *                                        (bearer_error still surfaced)
+ *   - /health ok,      /etag rejects   → plugin reachable, bearer rejected
+ *   - /health ok,      /etag ok        → green
+ *
+ * Never throws on probe failure — those land in the result fields.
+ * Throws only on truly unexpected programmer errors (e.g. the client
+ * arg is not a RestClient).
+ *
+ * @license MIT
+ */
+import { RestError } from '../errors.js';
+/**
+ * Run the canonical `/health` + `/etag` parallel probe against a
+ * site-bound {@link RestClient}.
+ *
+ * `Promise.allSettled` so a thrown probe never short-circuits the
+ * other — both legs always contribute to the final classification.
+ *
+ * The summary string is deterministic per `{plugin_reachable, bearer_valid}`
+ * combination so customer-facing UX (CLI table, MCP detail-card) is
+ * identical across the two surfaces.
+ */
+export async function probeSite(client) {
+    const [healthSettled, etagSettled] = await Promise.allSettled([
+        client.get('/health'),
+        client.get('/etag'),
+    ]);
+    let pluginReachable = false;
+    let bearerValid = false;
+    let etagReceived = false;
+    let pluginError;
+    let bearerError;
+    let httpStatusHealth;
+    let httpStatusEtag;
+    // /health leg — plain liveness probe (no auth required).
+    if (healthSettled.status === 'fulfilled') {
+        pluginReachable = true;
+    }
+    else {
+        const e = healthSettled.reason;
+        if (e instanceof RestError) {
+            httpStatusHealth = e.status;
+            pluginError = `HTTP ${String(e.status)}: ${e.message}`;
+        }
+        else if (e instanceof Error) {
+            pluginError = e.message;
+        }
+        else {
+            pluginError = String(e);
+        }
+    }
+    // /etag leg — bearer-gated. 401/403 means the plugin DID respond
+    // and the auth check fired — so we can confidently flip
+    // plugin_reachable even if /health hasn't already.
+    if (etagSettled.status === 'fulfilled') {
+        bearerValid = true;
+        etagReceived = true;
+    }
+    else {
+        const e = etagSettled.reason;
+        if (e instanceof RestError) {
+            httpStatusEtag = e.status;
+            bearerError = `HTTP ${String(e.status)}: ${e.message}`;
+            if (e.status === 401 || e.status === 403) {
+                pluginReachable = true;
+            }
+        }
+        else if (e instanceof Error) {
+            bearerError = e.message;
+        }
+        else {
+            bearerError = String(e);
+        }
+    }
+    const summary = pluginReachable && bearerValid
+        ? 'OK — plugin reachable and Bearer key accepted.'
+        : !pluginReachable
+            ? 'FAIL — plugin not reachable. Verify the site URL and that the yt-builder-mcp plugin is active.'
+            : 'FAIL — plugin reachable but Bearer key rejected. Regenerate the key or update the secret reference.';
+    return {
+        plugin_reachable: pluginReachable,
+        bearer_valid: bearerValid,
+        etag_received: etagReceived,
+        summary,
+        ...(pluginError !== undefined ? { plugin_error: pluginError } : {}),
+        ...(bearerError !== undefined ? { bearer_error: bearerError } : {}),
+        ...(httpStatusHealth !== undefined ? { http_status_health: httpStatusHealth } : {}),
+        ...(httpStatusEtag !== undefined ? { http_status_etag: httpStatusEtag } : {}),
+    };
+}
+//# sourceMappingURL=probe.js.map

package/dist/sites/probe.js.map

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