@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

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"}

package/dist/sites/schema.js

@@ -0,0 +1,71 @@
+/**
+ * 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 const SITE_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+/**
+ * 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 const OP_REF_REGEX = /^op:\/\/(?!.*\/\.\.\/)[A-Za-z0-9_/.-]+$/;
+/**
+ * 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 const BEARER_REGEX = /^ytb_(live|test)_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+/**
+ * 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 const SiteEntry = z.object({
+    site_id: z.string().min(1).max(64).regex(SITE_ID_REGEX),
+    url: z.string().url(),
+    platform: z.enum(['wordpress', 'joomla', 'auto']).default('auto'),
+    bearer: z.string().regex(BEARER_REGEX).optional(),
+    bearer_ref: z.string().regex(OP_REF_REGEX).optional(),
+    is_default: z.boolean().default(false),
+    label: z.string().max(120).optional(),
+    added_at: z.string().datetime().optional(),
+}).refine((s) => (s.bearer !== undefined) !== (s.bearer_ref !== undefined), { message: 'Exactly one of bearer or bearer_ref must be set' });
+/**
+ * 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 const SitesFile = z.object({
+    schema_version: z.literal(1),
+    default_site_id: z.string().regex(SITE_ID_REGEX).nullable(),
+    sites: z.array(SiteEntry),
+}).refine((f) => f.sites.filter((s) => s.is_default).length <= 1, { message: 'At most one site can have is_default:true' });
+//# sourceMappingURL=schema.js.map

package/dist/sites/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/sites/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,yCAAyC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,kDAAkD,CAAC;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC;IACvD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACjE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE;IACjD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE;IACrD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,EAChE,EAAE,OAAO,EAAE,iDAAiD,EAAE,CACjE,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;IAC3D,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC,CAAC,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,IAAI,CAAC,EACtD,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAC3D,CAAC"}

package/dist/sites/secret-resolver.d.ts

@@ -0,0 +1,115 @@
+/**
+ * W2 — Secret-Resolver: produce a bearer-token for a `SiteEntryT` at call
+ * time, supporting either a plain in-file token (`bearer`) or a 1Password
+ * Secret Reference (`bearer_ref`) resolved through the `op` CLI.
+ *
+ * Design choices (per plan §W2):
+ *  - **`execFile`, never `exec`/`spawn` with `shell:true`.** `op read <ref>`
+ *    must run as a direct `execve` with an argv array — no shell, no
+ *    metacharacter expansion. The W1 schema already enforces
+ *    {@link OP_REF_REGEX}; this module re-enforces it at the call site as
+ *    defence-in-depth (a hand-edited sites.json could otherwise sneak a
+ *    payload past validation).
+ *  - **5-second hard timeout.** `op` is interactive in some failure modes
+ *    (Touch-ID, biometric retry). We cap with a real timer + `kill()` to
+ *    avoid agent-loop wedging on a stalled subprocess.
+ *  - **Pluggable for testing.** The OpSecretResolver accepts an injected
+ *    `execFile` callback so tests can mock subprocess invocation without
+ *    monkey-patching the global `node:child_process` module.
+ *
+ * @license MIT
+ */
+import { type SiteEntryT } from './schema.js';
+/**
+ * Resolve the `op` binary to an absolute path so it works under a
+ * stripped-down GUI PATH. Precedence: explicit `YTB_MCP_OP_BINARY` env
+ * override → first existing well-known absolute path → bare `op` (PATH).
+ */
+export declare function resolveOpBinary(env?: NodeJS.ProcessEnv): string;
+/**
+ * Shape returned by every resolver. W12-R1.2 (A5-S3): the planned TTL
+ * cache that was the original justification for `resolvedAt` never
+ * shipped — the W4 ClientPool caches the `RestClient` itself, not the
+ * bearer — so the field was dead weight. Dropped to keep the contract
+ * minimal. Re-add ONLY when a real consumer appears.
+ */
+export interface ResolvedBearer {
+    readonly token: string;
+    readonly source: 'plain' | 'op';
+}
+/**
+ * Pluggable resolver contract. Implementations MUST NOT log the token,
+ * MUST NOT mutate the input site, and MUST throw {@link SecretResolverError}
+ * on any failure (never return an empty/placeholder bearer).
+ */
+export interface SecretResolver {
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+}
+/** Domain-tagged error so callers (auth, client) can branch on `code`. */
+export declare class SecretResolverError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Signature of `node:child_process.execFile` reduced to the callback we
+ * actually rely on. Injecting this lets tests provide a deterministic
+ * substitute without `vi.mock('node:child_process')` side-effects.
+ *
+ * The real `execFile` overload returns a `ChildProcess` and accepts
+ * many option shapes; we accept the broadest superset and only use the
+ * pieces the resolver needs (`timeout`, `signal`, callback args).
+ */
+export type ExecFileLike = (file: string, args: readonly string[], options: {
+    timeout?: number;
+    maxBuffer?: number;
+}, callback: (error: (Error & {
+    code?: string | number;
+    signal?: string;
+}) | null, stdout: string, stderr: string) => void) => void;
+/**
+ * Plain in-file bearer — used when `site.bearer` is populated. Returns the
+ * stored token verbatim, with `source:'plain'`.
+ */
+export declare class PlainSecretResolver implements SecretResolver {
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+}
+/**
+ * Resolves `bearer_ref` (`op://vault/item/field`) through the 1Password CLI.
+ *
+ * Failure surface:
+ *  - Missing `bearer_ref`             → `OP_REF_MISSING`
+ *  - Malformed ref at call site       → `OP_REF_INVALID`
+ *  - `op` binary not on PATH (ENOENT) → `OP_CLI_MISSING`
+ *  - `op` exit-code 6 (not signed in) → `OP_NOT_SIGNED_IN`
+ *  - 5-second timeout exceeded        → `OP_TIMEOUT`
+ *  - Empty/whitespace stdout          → `OP_EMPTY_OUTPUT`
+ *  - Any other non-zero exit          → `OP_EXEC_FAILED`
+ */
+export declare class OpSecretResolver implements SecretResolver {
+    private readonly opBinary;
+    private readonly execFile;
+    private readonly timeoutMs;
+    constructor(opBinary?: string, execFile?: ExecFileLike, timeoutMs?: number);
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+    /**
+     * Invokes `op read <ref>` with a hard timeout. The promise is wrapped
+     * so a stalled subprocess (e.g. waiting on biometric prompt) cannot
+     * outlive {@link timeoutMs}.
+     */
+    private runOpRead;
+    private mapExecError;
+}
+/**
+ * Composite resolver — chooses Plain/Op per site at resolve-time. This is
+ * the resolver wired into the registry in W4; W2 ships it standalone so
+ * unit tests cover the routing logic in isolation from any caching.
+ */
+export declare class CompositeSecretResolver implements SecretResolver {
+    private readonly plain;
+    private readonly op;
+    constructor(plain?: SecretResolver, op?: SecretResolver);
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+}
+/** Default factory consumed by the W4 registry / W5 auth pipeline. */
+export declare function defaultSecretResolver(): CompositeSecretResolver;
+//# sourceMappingURL=secret-resolver.d.ts.map

package/dist/sites/secret-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-resolver.d.ts","sourceRoot":"","sources":["../../src/sites/secret-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAqB5D;;;;GAIG;AACH,wBAAgB,eAAe,CAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACrC,MAAM,CAWR;AAQD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACtD;AAED,0EAA0E;AAC1E,qBAAa,mBAAoB,SAAQ,KAAK;aACd,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI5D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CACvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,QAAQ,EAAE,CACN,KAAK,EAAE,CAAC,KAAK,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,EACnE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,KACb,IAAI,KACR,IAAI,CAAC;AAqBV;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAChD,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;CAa3D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IAE/C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFT,QAAQ,GAAE,MAA0B,EACpC,QAAQ,GAAE,YAA8B,EACxC,SAAS,GAAE,MAAsB;IAGhD,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;IAmCxD;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,YAAY;CAoDvB;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,YAAW,cAAc;IAEtD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBADF,KAAK,GAAE,cAA0C,EACjD,EAAE,GAAE,cAAuC;IAG1D,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;CAM3D;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,IAAI,uBAAuB,CAE/D"}