@wootsup/yt-builder-mcp 1.0.0 → 1.1.0

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAkBzC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAkB;IAC9C,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;QAC1D,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;KACtB,CAAC,CAAC;IAEH,IAAI,eAAe,GAAG,KAAK,CAAC;IAC5B,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,WAA+B,CAAC;IACpC,IAAI,WAA+B,CAAC;IACpC,IAAI,gBAAoC,CAAC;IACzC,IAAI,cAAkC,CAAC;IAEvC,yDAAyD;IACzD,IAAI,aAAa,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACvC,eAAe,GAAG,IAAI,CAAC;IAC3B,CAAC;SAAM,CAAC;QACJ,MAAM,CAAC,GAAY,aAAa,CAAC,MAAM,CAAC;QACxC,IAAI,CAAC,YAAY,SAAS,EAAE,CAAC;YACzB,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;YAC5B,WAAW,GAAG,QAAQ,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3D,CAAC;aAAM,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;YAC5B,WAAW,GAAG,CAAC,CAAC,OAAO,CAAC;QAC5B,CAAC;aAAM,CAAC;YACJ,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;IAED,iEAAiE;IACjE,wDAAwD;IACxD,mDAAmD;IACnD,IAAI,WAAW,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACrC,WAAW,GAAG,IAAI,CAAC;QACnB,YAAY,GAAG,IAAI,CAAC;IACxB,CAAC;SAAM,CAAC;QACJ,MAAM,CAAC,GAAY,WAAW,CAAC,MAAM,CAAC;QACtC,IAAI,CAAC,YAAY,SAAS,EAAE,CAAC;YACzB,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;YAC1B,WAAW,GAAG,QAAQ,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YACvD,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACvC,eAAe,GAAG,IAAI,CAAC;YAC3B,CAAC;QACL,CAAC;aAAM,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;YAC5B,WAAW,GAAG,CAAC,CAAC,OAAO,CAAC;QAC5B,CAAC;aAAM,CAAC;YACJ,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,eAAe,IAAI,WAAW;QAC1C,CAAC,CAAC,gDAAgD;QAClD,CAAC,CAAC,CAAC,eAAe;YACd,CAAC,CAAC,gGAAgG;YAClG,CAAC,CAAC,qGAAqG,CAAC;IAEhH,OAAO;QACH,gBAAgB,EAAE,eAAe;QACjC,YAAY,EAAE,WAAW;QACzB,aAAa,EAAE,YAAY;QAC3B,OAAO;QACP,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;AACN,CAAC"}

package/dist/sites/registry.d.ts

@@ -0,0 +1,142 @@
+/**
+ * W3 — Site Registry + Platform-Cache.
+ *
+ * Wraps a parsed {@link SitesFileT} and provides:
+ *  - O(1) {@link SiteRegistry.get|get(site_id)} lookup.
+ *  - Insertion-order {@link SiteRegistry.listIds|listIds()} for stable
+ *    UX in the W7 `sites_list` tool.
+ *  - {@link SiteRegistry.defaultSiteId|defaultSiteId()} that respects
+ *    the explicit `default_site_id` first, then falls back to the
+ *    flagged `is_default:true` entry, then `null`. Auto-promotion of a
+ *    lone site to default is intentionally NOT done here — that policy
+ *    belongs to the W4 caller layer.
+ *  - {@link SiteRegistry.platformFor|platformFor(site_id)} that
+ *    memoises the resolved {@link Platform} via a
+ *    `Map<string, Promise<Platform>>`. Storing the **Promise** (not the
+ *    resolved value) is load-bearing: N parallel first-time callers
+ *    share the SAME probe (`platformForUrlAsync`) instead of racing N
+ *    probes against the same site origin. The plan §W3 calls this out
+ *    explicitly ("Promise-cache, not just result-cache").
+ *  - {@link SiteRegistry.listForDisplay|listForDisplay()} that surfaces
+ *    a tabular view for the upcoming W7 sites_list tool. The
+ *    `platform_resolved` field is intentionally only populated AFTER
+ *    {@link SiteRegistry.platformFor|platformFor()} has been called for
+ *    that site_id — listForDisplay() must NEVER trigger a probe on its
+ *    own (that would defeat the "no surprise network calls in
+ *    list-tools" contract).
+ *
+ * @license MIT
+ */
+import { type Platform, type PlatformKind } from '../platform/index.js';
+import type { SiteEntryT, SitesFileT } from './schema.js';
+/**
+ * Display-side row used by the W7 `sites_list` tool. `bearer_source` is
+ * derived from whether the underlying {@link SiteEntryT} has `bearer`
+ * (plain) or `bearer_ref` (1Password); the resolver itself is not
+ * needed to compute this hint, so we can render the list without ever
+ * invoking the 1Password CLI.
+ *
+ * `platform_resolved` is only set once {@link SiteRegistry.platformFor}
+ * has run for that site_id at least once — it is a "peek" into the
+ * memo cache, never a trigger for a new probe.
+ */
+export interface SiteRowT {
+    site_id: string;
+    url: string;
+    platform_resolved?: 'wordpress' | 'joomla';
+    platform_hint: 'wordpress' | 'joomla' | 'auto';
+    is_default: boolean;
+    label?: string;
+    bearer_source: 'plain' | 'op';
+}
+/**
+ * Caller-side projection of a registry entry, with the `Platform`
+ * already resolved and the bearer-source flagged for downstream logs.
+ * Reserved for future call-sites that want the fully-resolved bundle
+ * in a single object — the tool builder layer will populate this.
+ */
+export interface ResolvedSite {
+    readonly id: string;
+    readonly url: string;
+    readonly platform: Platform;
+    readonly isDefault: boolean;
+    readonly label?: string;
+    readonly bearerSource: 'plain' | 'op';
+}
+/**
+ * Optional injection point for tests. Production callers should never
+ * pass this — they get the default `platformForUrlAsync` from the
+ * platform barrel, which itself does the runtime probe.
+ */
+export interface SiteRegistryOptions {
+    readonly platformForUrlAsync?: (url: string, hint?: PlatformKind) => Promise<Platform>;
+}
+/**
+ * In-memory registry around a parsed sites file. NEVER mutates the
+ * input `file`; all "writes" go through {@link saveSitesFile} on the
+ * store side, which produces a fresh `SitesFileT` to wrap in a new
+ * registry instance.
+ */
+export declare class SiteRegistry {
+    private readonly file;
+    /**
+     * Promise-memo for platform resolution. The KEY is the site_id;
+     * the VALUE is the in-flight or already-resolved Promise. Parallel
+     * callers for the same site_id all receive the same promise and
+     * therefore share the one probe.
+     */
+    private readonly platformCache;
+    /**
+     * Sync-side mirror of `platformCache` that records the resolved
+     * `PlatformKind` once the probe completes. Powers
+     * {@link listForDisplay} without forcing it to await or to trigger
+     * a probe. Entries land here only AFTER the probe resolves
+     * successfully; rejected probes leave the entry absent.
+     */
+    private readonly resolvedKinds;
+    private readonly probe;
+    constructor(file: SitesFileT, opts?: SiteRegistryOptions);
+    /**
+     * Returns the configured default site_id. Resolution order:
+     *   1. `file.default_site_id` if set AND points at an entry that
+     *      actually exists in `file.sites`.
+     *   2. The first `is_default:true` entry (W1 schema guarantees at
+     *      most one).
+     *   3. `null` — no default; the W4 caller layer decides whether
+     *      to auto-promote a lone site.
+     */
+    defaultSiteId(): string | null;
+    /**
+     * site_id list in insertion order (the order they appear in
+     * `file.sites`). Stable across registry rebuilds because the
+     * store preserves array order on save.
+     */
+    listIds(): readonly string[];
+    /**
+     * Returns the raw entry for a site_id, or `null` when unknown.
+     * O(n) on the entry count — fine for the realistic upper bound
+     * (~100 sites per customer).
+     */
+    get(siteId: string): SiteEntryT | null;
+    /**
+     * Resolves the {@link Platform} for `siteId` and memoises the
+     * Promise. Subsequent calls (including ones still in-flight)
+     * return the same Promise — exactly one probe per site_id, even
+     * across N parallel callers.
+     *
+     * @throws Error when the site_id is unknown. Callers should
+     *   pre-check with {@link get}.
+     */
+    platformFor(siteId: string): Promise<Platform>;
+    /**
+     * Map view of the registry for the W7 `sites_list` tool. NEVER
+     * triggers a probe: `platform_resolved` is undefined for any site
+     * whose `platformFor()` has not yet been called.
+     *
+     * `bearer_source` is derived from the W1 schema invariant
+     * (exactly one of `bearer`/`bearer_ref` is set) so listing never
+     * needs to consult the W2 secret-resolver.
+     */
+    listForDisplay(): readonly SiteRowT[];
+}
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/sites/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACH,KAAK,QAAQ,EAEb,KAAK,YAAY,EACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC3C,aAAa,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/C,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAC3B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,YAAY,KAClB,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IAwBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAvBzB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IAEtE;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IAEjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGC;gBAGF,IAAI,EAAE,UAAU,EACjC,IAAI,GAAE,mBAAwB;IAKlC;;;;;;;;OAQG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAY9B;;;;OAIG;IACH,OAAO,IAAI,SAAS,MAAM,EAAE;IAI5B;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAItC;;;;;;;;OAQG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAyCpD;;;;;;;;OAQG;IACH,cAAc,IAAI,SAAS,QAAQ,EAAE;CAkBxC"}

package/dist/sites/registry.js

@@ -0,0 +1,163 @@
+/**
+ * W3 — Site Registry + Platform-Cache.
+ *
+ * Wraps a parsed {@link SitesFileT} and provides:
+ *  - O(1) {@link SiteRegistry.get|get(site_id)} lookup.
+ *  - Insertion-order {@link SiteRegistry.listIds|listIds()} for stable
+ *    UX in the W7 `sites_list` tool.
+ *  - {@link SiteRegistry.defaultSiteId|defaultSiteId()} that respects
+ *    the explicit `default_site_id` first, then falls back to the
+ *    flagged `is_default:true` entry, then `null`. Auto-promotion of a
+ *    lone site to default is intentionally NOT done here — that policy
+ *    belongs to the W4 caller layer.
+ *  - {@link SiteRegistry.platformFor|platformFor(site_id)} that
+ *    memoises the resolved {@link Platform} via a
+ *    `Map<string, Promise<Platform>>`. Storing the **Promise** (not the
+ *    resolved value) is load-bearing: N parallel first-time callers
+ *    share the SAME probe (`platformForUrlAsync`) instead of racing N
+ *    probes against the same site origin. The plan §W3 calls this out
+ *    explicitly ("Promise-cache, not just result-cache").
+ *  - {@link SiteRegistry.listForDisplay|listForDisplay()} that surfaces
+ *    a tabular view for the upcoming W7 sites_list tool. The
+ *    `platform_resolved` field is intentionally only populated AFTER
+ *    {@link SiteRegistry.platformFor|platformFor()} has been called for
+ *    that site_id — listForDisplay() must NEVER trigger a probe on its
+ *    own (that would defeat the "no surprise network calls in
+ *    list-tools" contract).
+ *
+ * @license MIT
+ */
+import { platformForUrlAsync, } from '../platform/index.js';
+/**
+ * In-memory registry around a parsed sites file. NEVER mutates the
+ * input `file`; all "writes" go through {@link saveSitesFile} on the
+ * store side, which produces a fresh `SitesFileT` to wrap in a new
+ * registry instance.
+ */
+export class SiteRegistry {
+    file;
+    /**
+     * Promise-memo for platform resolution. The KEY is the site_id;
+     * the VALUE is the in-flight or already-resolved Promise. Parallel
+     * callers for the same site_id all receive the same promise and
+     * therefore share the one probe.
+     */
+    platformCache = new Map();
+    /**
+     * Sync-side mirror of `platformCache` that records the resolved
+     * `PlatformKind` once the probe completes. Powers
+     * {@link listForDisplay} without forcing it to await or to trigger
+     * a probe. Entries land here only AFTER the probe resolves
+     * successfully; rejected probes leave the entry absent.
+     */
+    resolvedKinds = new Map();
+    probe;
+    constructor(file, opts = {}) {
+        this.file = file;
+        this.probe = opts.platformForUrlAsync ?? platformForUrlAsync;
+    }
+    /**
+     * Returns the configured default site_id. Resolution order:
+     *   1. `file.default_site_id` if set AND points at an entry that
+     *      actually exists in `file.sites`.
+     *   2. The first `is_default:true` entry (W1 schema guarantees at
+     *      most one).
+     *   3. `null` — no default; the W4 caller layer decides whether
+     *      to auto-promote a lone site.
+     */
+    defaultSiteId() {
+        const explicit = this.file.default_site_id;
+        if (explicit !== null
+            && this.file.sites.some((s) => s.site_id === explicit)) {
+            return explicit;
+        }
+        const flagged = this.file.sites.find((s) => s.is_default);
+        return flagged ? flagged.site_id : null;
+    }
+    /**
+     * site_id list in insertion order (the order they appear in
+     * `file.sites`). Stable across registry rebuilds because the
+     * store preserves array order on save.
+     */
+    listIds() {
+        return this.file.sites.map((s) => s.site_id);
+    }
+    /**
+     * Returns the raw entry for a site_id, or `null` when unknown.
+     * O(n) on the entry count — fine for the realistic upper bound
+     * (~100 sites per customer).
+     */
+    get(siteId) {
+        return this.file.sites.find((s) => s.site_id === siteId) ?? null;
+    }
+    /**
+     * Resolves the {@link Platform} for `siteId` and memoises the
+     * Promise. Subsequent calls (including ones still in-flight)
+     * return the same Promise — exactly one probe per site_id, even
+     * across N parallel callers.
+     *
+     * @throws Error when the site_id is unknown. Callers should
+     *   pre-check with {@link get}.
+     */
+    async platformFor(siteId) {
+        const cached = this.platformCache.get(siteId);
+        if (cached !== undefined)
+            return cached;
+        const entry = this.get(siteId);
+        if (entry === null) {
+            throw new Error(`SiteRegistry: unknown site_id "${siteId}"`);
+        }
+        // Build the promise synchronously and insert into the cache
+        // BEFORE awaiting anything — this is what makes parallel
+        // callers share the probe. If `entry.platform` is a concrete
+        // hint we still wrap in Promise.resolve so the cache type is
+        // uniform.
+        const probePromise = entry.platform === 'auto'
+            ? this.probe(entry.url)
+            : this.probe(entry.url, entry.platform);
+        // Tee off a side-channel that records the resolved kind into
+        // the sync mirror map so `listForDisplay()` can surface it
+        // without awaiting. We swallow rejections here because the
+        // original caller (the awaiter of `platformFor`) owns the
+        // error contract; the mirror map simply stays empty on
+        // failure.
+        const memoised = probePromise.then((platform) => {
+            this.resolvedKinds.set(siteId, platform.kind);
+            return platform;
+        }, (err) => {
+            // Re-throw so awaiters see the failure, but do not
+            // populate the sync mirror.
+            throw err instanceof Error ? err : new Error(String(err));
+        });
+        this.platformCache.set(siteId, memoised);
+        return memoised;
+    }
+    /**
+     * Map view of the registry for the W7 `sites_list` tool. NEVER
+     * triggers a probe: `platform_resolved` is undefined for any site
+     * whose `platformFor()` has not yet been called.
+     *
+     * `bearer_source` is derived from the W1 schema invariant
+     * (exactly one of `bearer`/`bearer_ref` is set) so listing never
+     * needs to consult the W2 secret-resolver.
+     */
+    listForDisplay() {
+        return this.file.sites.map((entry) => {
+            const resolved = this.resolvedKinds.get(entry.site_id);
+            const bearerSource = entry.bearer !== undefined ? 'plain' : 'op';
+            const row = {
+                site_id: entry.site_id,
+                url: entry.url,
+                platform_hint: entry.platform,
+                is_default: entry.is_default,
+                bearer_source: bearerSource,
+            };
+            if (resolved !== undefined)
+                row.platform_resolved = resolved;
+            if (entry.label !== undefined)
+                row.label = entry.label;
+            return row;
+        });
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/sites/registry.js.map

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

package/dist/sites/schema.d.ts

@@ -0,0 +1,90 @@
+/**
+ * W1 — Sites-Storage Foundation: Zod schemas for the on-disk sites file.
+ *
+ * Schema spec frozen by `2026-05-25-04-yt-builder-mcp-multi-site-implementation.md`
+ * §W1. Do NOT rename fields without bumping `schema_version` and adding a
+ * migration in W3 (registry).
+ *
+ * The on-disk format is JSON. Each entry represents one connected
+ * YOOtheme-Pro-equipped site. A site MUST carry either an inline `bearer`
+ * (plain text, for local-dev) OR an `op://` 1Password Secret Reference
+ * (`bearer_ref`), never both — enforced via {@link SiteEntry}'s refine().
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+/**
+ * Allowed character set for a `site_id`. Letters, digits, underscore,
+ * dash — no spaces, no path separators, no shell metacharacters.
+ *
+ * Surface: filename-safe, URL-path-safe, log-safe.
+ */
+export declare const SITE_ID_REGEX: RegExp;
+/**
+ * 1Password Secret Reference shape (`op://<vault>/<item>/<field>` and
+ * deeper). Letters, digits, underscore, slash, dot, dash only — same
+ * defence-in-depth set the W2 SecretResolver will re-validate before
+ * shelling out to `op`.
+ *
+ * W12-R1.3 (A2-L1): the previous pattern allowed `..` path segments
+ * because `.` was in the character class. The `op` CLI does not honour
+ * filesystem-style traversal but the input was reaching shell argv
+ * verbatim, so a ref like `op://vault/../something` (or worse, encoded
+ * in a hand-edited sites.json) muddied the trust boundary. The
+ * negative lookahead `(?!.*\/\.\.\/)` rejects any ref containing a
+ * `/../` segment without disallowing legitimate `.` in vault/item
+ * names (e.g. `op://team.acme/...`).
+ */
+export declare const OP_REF_REGEX: RegExp;
+/**
+ * Bearer-token shape produced by `KeyService.php`:
+ * `ytb_(live|test)_<payloadB64Url>.<sigB64Url>`. Re-validated here so a
+ * hand-edited sites.json can never inject a token shape the server would
+ * reject anyway.
+ */
+export declare const BEARER_REGEX: RegExp;
+/**
+ * One site entry. Carries identity (`site_id`), reachability (`url` +
+ * `platform`), credential (exactly one of `bearer`/`bearer_ref`), and
+ * presentation metadata (`is_default`, `label`, `added_at`).
+ */
+export declare const SiteEntry: z.ZodObject<{
+    site_id: z.ZodString;
+    url: z.ZodString;
+    platform: z.ZodDefault<z.ZodEnum<{
+        wordpress: "wordpress";
+        joomla: "joomla";
+        auto: "auto";
+    }>>;
+    bearer: z.ZodOptional<z.ZodString>;
+    bearer_ref: z.ZodOptional<z.ZodString>;
+    is_default: z.ZodDefault<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    added_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The on-disk sites-file root. `schema_version` is a literal `1` for now;
+ * future schema migrations bump it AND add a migration step in the W3
+ * registry loader.
+ */
+export declare const SitesFile: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    default_site_id: z.ZodNullable<z.ZodString>;
+    sites: z.ZodArray<z.ZodObject<{
+        site_id: z.ZodString;
+        url: z.ZodString;
+        platform: z.ZodDefault<z.ZodEnum<{
+            wordpress: "wordpress";
+            joomla: "joomla";
+            auto: "auto";
+        }>>;
+        bearer: z.ZodOptional<z.ZodString>;
+        bearer_ref: z.ZodOptional<z.ZodString>;
+        is_default: z.ZodDefault<z.ZodBoolean>;
+        label: z.ZodOptional<z.ZodString>;
+        added_at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SiteEntryT = z.infer<typeof SiteEntry>;
+export type SitesFileT = z.infer<typeof SitesFile>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/sites/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAqB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,QAA4C,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAAqD,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;iBAYrB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;iBAOrB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AACnD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC"}