@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/dist/sites/secret-resolver.js

@@ -0,0 +1,225 @@
+/**
+ * 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 { execFile as nodeExecFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { OP_REF_REGEX } from './schema.js';
+/** Hard cap for any single `op read` invocation. */
+const OP_TIMEOUT_MS = 5_000;
+/**
+ * Common absolute install locations for the 1Password CLI. GUI-spawned
+ * MCP hosts (Claude Desktop, etc.) launch the server subprocess with a
+ * minimal PATH that usually omits `/opt/homebrew/bin` and `/usr/local/bin`,
+ * so a bare `op` resolves to ENOENT even when the user has `op` working in
+ * their shell. We probe these absolute paths before falling back to PATH.
+ *
+ * Order: Homebrew (Apple Silicon) → Homebrew/manual (Intel + /usr/local) →
+ * Linux package managers → PATH.
+ */
+const OP_BINARY_CANDIDATES = [
+    '/opt/homebrew/bin/op',
+    '/usr/local/bin/op',
+    '/usr/bin/op',
+];
+/**
+ * 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 function resolveOpBinary(env = process.env) {
+    const override = (env.YTB_MCP_OP_BINARY ?? '').trim();
+    if (override.length > 0)
+        return override;
+    for (const candidate of OP_BINARY_CANDIDATES) {
+        try {
+            if (existsSync(candidate))
+                return candidate;
+        }
+        catch {
+            // ignore stat errors and keep probing
+        }
+    }
+    return 'op';
+}
+/** `op` CLI exit-code → friendly hint mapping. */
+const OP_EXIT_CODE_HINTS = {
+    6: 'Not signed in to 1Password CLI. Run `op signin` and retry.',
+    1: 'Generic op CLI error — verify the secret reference exists and the vault is accessible.',
+};
+/** Domain-tagged error so callers (auth, client) can branch on `code`. */
+export class SecretResolverError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SecretResolverError';
+    }
+}
+/** Default factory wrapping Node's real `execFile`. Adapter for type-shape. */
+const defaultExecFile = (file, args, options, callback) => {
+    // Pass `encoding: 'utf8'` explicitly so stdout/stderr are guaranteed
+    // strings, not Buffers. The execFile overload resolution returns `string`
+    // for both when `encoding` is set.
+    nodeExecFile(file, args, { ...options, encoding: 'utf8' }, (err, stdout, stderr) => {
+        callback(err, stdout, stderr);
+    });
+};
+/**
+ * Plain in-file bearer — used when `site.bearer` is populated. Returns the
+ * stored token verbatim, with `source:'plain'`.
+ */
+export class PlainSecretResolver {
+    async resolve(site) {
+        const token = site.bearer;
+        if (token === undefined || token.length === 0) {
+            throw new SecretResolverError('PLAIN_BEARER_MISSING', `Site '${site.site_id}' has no inline 'bearer' — set one or configure 'bearer_ref'.`);
+        }
+        return {
+            token,
+            source: 'plain',
+        };
+    }
+}
+/**
+ * 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 class OpSecretResolver {
+    opBinary;
+    execFile;
+    timeoutMs;
+    constructor(opBinary = resolveOpBinary(), execFile = defaultExecFile, timeoutMs = OP_TIMEOUT_MS) {
+        this.opBinary = opBinary;
+        this.execFile = execFile;
+        this.timeoutMs = timeoutMs;
+    }
+    async resolve(site) {
+        const ref = site.bearer_ref;
+        if (ref === undefined || ref.length === 0) {
+            throw new SecretResolverError('OP_REF_MISSING', `Site '${site.site_id}' has no 'bearer_ref' — OpSecretResolver requires one.`);
+        }
+        // Defence-in-depth: re-validate the ref shape at the call site,
+        // BEFORE we hand the string to a subprocess. The W1 schema also
+        // enforces this on load/save, but a hand-edited or hot-loaded
+        // sites.json could in theory bypass that.
+        if (!OP_REF_REGEX.test(ref)) {
+            throw new SecretResolverError('OP_REF_INVALID', `Site '${site.site_id}' has an invalid 'bearer_ref' shape — must match op://<vault>/<item>/<field>.`);
+        }
+        const stdout = await this.runOpRead(ref);
+        const token = stdout.trim();
+        if (token.length === 0) {
+            throw new SecretResolverError('OP_EMPTY_OUTPUT', `op returned empty output for '${ref}' — verify the field exists and is non-empty.`);
+        }
+        return {
+            token,
+            source: 'op',
+        };
+    }
+    /**
+     * 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}.
+     */
+    runOpRead(ref) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new SecretResolverError('OP_TIMEOUT', `op read '${ref}' exceeded ${this.timeoutMs}ms — is 1Password CLI hung on a biometric prompt?`));
+            }, this.timeoutMs);
+            // Allow the test process to exit even if `op` is still pending.
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this.execFile(this.opBinary, ['read', ref], { timeout: this.timeoutMs, maxBuffer: 1024 * 64 }, (err, stdout, stderr) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (err) {
+                    reject(this.mapExecError(err, stderr, ref));
+                    return;
+                }
+                resolve(stdout);
+            });
+        });
+    }
+    mapExecError(err, stderr, ref) {
+        const codeStr = typeof err.code === 'string' ? err.code : '';
+        const codeNum = typeof err.code === 'number' ? err.code : NaN;
+        if (codeStr === 'ENOENT') {
+            return new SecretResolverError('OP_CLI_MISSING', `op CLI not found in PATH — install 1Password CLI or use plain bearer field instead of bearer_ref.`);
+        }
+        // W12-R1.2 (A5-S4): the `op` CLI returns "isn't an item" / "item
+        // not found" on stderr when the ref points to a nonexistent item.
+        // Surfaced as generic OP_EXEC_FAILED pre-W12, which left the
+        // customer guessing whether their ref shape was wrong vs whether
+        // the item was deleted. Brand it explicitly so the recovery hint
+        // can name the right knob.
+        const stderrLower = (stderr || '').toLowerCase();
+        if (stderrLower.includes(`isn't an item`)
+            || stderrLower.includes('item not found')) {
+            return new SecretResolverError('OP_ITEM_NOT_FOUND', `1Password item not found at '${ref}'. `
+                + 'Verify the ref points to an existing item, or update sites.json bearer_ref.');
+        }
+        if (Number.isFinite(codeNum)) {
+            const hint = OP_EXIT_CODE_HINTS[codeNum];
+            if (codeNum === 6) {
+                return new SecretResolverError('OP_NOT_SIGNED_IN', hint ?? `op exited 6 — not signed in.`);
+            }
+            return new SecretResolverError('OP_EXEC_FAILED', `op read '${ref}' failed with exit ${codeNum}: ${(stderr || '').trim() || (hint ?? 'no stderr')}`);
+        }
+        return new SecretResolverError('OP_EXEC_FAILED', `op read '${ref}' failed: ${err.message}`);
+    }
+}
+/**
+ * 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 class CompositeSecretResolver {
+    plain;
+    op;
+    constructor(plain = new PlainSecretResolver(), op = new OpSecretResolver()) {
+        this.plain = plain;
+        this.op = op;
+    }
+    async resolve(site) {
+        if (site.bearer_ref !== undefined) {
+            return this.op.resolve(site);
+        }
+        return this.plain.resolve(site);
+    }
+}
+/** Default factory consumed by the W4 registry / W5 auth pipeline. */
+export function defaultSecretResolver() {
+    return new CompositeSecretResolver();
+}
+//# sourceMappingURL=secret-resolver.js.map

package/dist/sites/secret-resolver.js.map

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

package/dist/sites/store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * W1 — Sites-Storage Foundation: load/save the sites file.
+ *
+ * Guarantees:
+ *  - **Atomic replace.** Writes go to a sibling `*.tmp.<rand>` file, are
+ *    fsynced, chmod'd to 0600, and then `rename(2)`d over the target.
+ *    A SIGINT/SIGKILL between any two of these steps leaves either the
+ *    old file intact or the new file fully written — never a torn write.
+ *  - **Lock for concurrent writers.** `proper-lockfile` acquires an
+ *    advisory lockfile (`<file>.lock`) before any read/modify/write
+ *    cycle. Default `stale: 10000` ms; second concurrent save retries
+ *    with exponential back-off (`retries: 10, minTimeout: 50`).
+ *  - **0600 mode on write.** The temp file is opened/chmod'd to 0600
+ *    BEFORE the rename so the new inode never exists with looser perms,
+ *    even for one fsync window.
+ *  - **Schema-version gate.** Refuses to load a file with a version we
+ *    don't understand — explicit error, never silent migration.
+ *
+ * @license MIT
+ */
+import { type SitesFileT } from './schema.js';
+/** Base class for any sites-file IO/format failure. */
+export declare class SitesFileError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Thrown when the on-disk file declares a `schema_version` we don't know. */
+export declare class SchemaVersionError extends SitesFileError {
+    readonly found: unknown;
+    constructor(found: unknown);
+}
+/**
+ * Discriminated lock-acquisition failure. W12-R1.2 (A4-F1): the
+ * pre-W12 `SitesFileError` collapsed three distinct failure modes into
+ * one opaque "lock not acquired" string. Operators triaging a stuck
+ * setup wizard need to distinguish them to choose the right recovery:
+ *
+ *   - LOCK_TIMEOUT    → another setup process is currently writing.
+ *                       Wait + retry; do NOT touch the lockfile.
+ *   - LOCK_ORPHAN     → stale lock from a crashed prior process.
+ *                       Manual `rm <lockfilePath>` is the only fix.
+ *   - LOCK_PERMISSION → the lock dir itself is not writable. Fix
+ *                       file-system permissions.
+ *
+ * The `lockCode` discriminant + `lockfilePath` field let CLI surfaces
+ * (and pre-flight automation) emit precise hints.
+ */
+export type SitesFileLockCode = 'LOCK_TIMEOUT' | 'LOCK_ORPHAN' | 'LOCK_PERMISSION';
+export declare class SitesFileLockError extends SitesFileError {
+    readonly lockCode: SitesFileLockCode;
+    readonly lockfilePath: string;
+    constructor(lockCode: SitesFileLockCode, lockfilePath: string, message: string, cause?: unknown);
+}
+/**
+ * Returns the empty seed used when a sites file does not yet exist.
+ * Callers (W3 registry) detect "no file → run env-bridge fallback".
+ */
+export declare function emptySitesFile(): SitesFileT;
+/**
+ * Load + validate a sites file.
+ *
+ * Returns {@link emptySitesFile} when the path does not exist (no error).
+ * Throws {@link SchemaVersionError} for a known-unknown version and
+ * {@link SitesFileError} for JSON-parse or Zod-validation failures.
+ */
+export declare function loadSitesFile(path: string): Promise<SitesFileT>;
+/**
+ * Persist + validate a sites file atomically with chmod 0600.
+ *
+ * Pipeline:
+ *  1. Acquire `<path>.lock` via proper-lockfile (with retries).
+ *  2. Validate `data` through {@link SitesFile} (rejects bad input
+ *     before touching the filesystem).
+ *  3. Ensure parent directory exists.
+ *  4. Write JSON to `<path>.tmp.<pid>.<rand>`, fsync, chmod 0600.
+ *  5. `renameSync` over `<path>`.
+ *  6. Release lock.
+ *
+ * Tmp-file cleanup on any failure path.
+ */
+export declare function saveSitesFile(path: string, data: SitesFileT): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sites/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAkBH,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzD,uDAAuD;AACvD,qBAAa,cAAe,SAAQ,KAAK;aACQ,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAI/D;AAED,8EAA8E;AAC9E,qBAAa,kBAAmB,SAAQ,cAAc;aACtB,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;CAQ7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,aAAa,GAAG,iBAAiB,CAAC;AAEnF,qBAAa,kBAAmB,SAAQ,cAAc;aAE9B,QAAQ,EAAE,iBAAiB;aAC3B,YAAY,EAAE,MAAM;gBADpB,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,MAAM,EACpC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAKtB;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAE3C;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAiCrE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAoFjF"}

package/dist/sites/store.js

@@ -0,0 +1,198 @@
+/**
+ * W1 — Sites-Storage Foundation: load/save the sites file.
+ *
+ * Guarantees:
+ *  - **Atomic replace.** Writes go to a sibling `*.tmp.<rand>` file, are
+ *    fsynced, chmod'd to 0600, and then `rename(2)`d over the target.
+ *    A SIGINT/SIGKILL between any two of these steps leaves either the
+ *    old file intact or the new file fully written — never a torn write.
+ *  - **Lock for concurrent writers.** `proper-lockfile` acquires an
+ *    advisory lockfile (`<file>.lock`) before any read/modify/write
+ *    cycle. Default `stale: 10000` ms; second concurrent save retries
+ *    with exponential back-off (`retries: 10, minTimeout: 50`).
+ *  - **0600 mode on write.** The temp file is opened/chmod'd to 0600
+ *    BEFORE the rename so the new inode never exists with looser perms,
+ *    even for one fsync window.
+ *  - **Schema-version gate.** Refuses to load a file with a version we
+ *    don't understand — explicit error, never silent migration.
+ *
+ * @license MIT
+ */
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import lockfile from 'proper-lockfile';
+import { SitesFile } from './schema.js';
+/** Base class for any sites-file IO/format failure. */
+export class SitesFileError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'SitesFileError';
+    }
+}
+/** Thrown when the on-disk file declares a `schema_version` we don't know. */
+export class SchemaVersionError extends SitesFileError {
+    found;
+    constructor(found) {
+        super(`Unsupported sites-file schema_version: ${String(found)}. ` +
+            `This build supports schema_version: 1. ` +
+            `Upgrade @wootsup/yt-builder-mcp or revert the file.`);
+        this.found = found;
+        this.name = 'SchemaVersionError';
+    }
+}
+export class SitesFileLockError extends SitesFileError {
+    lockCode;
+    lockfilePath;
+    constructor(lockCode, lockfilePath, message, cause) {
+        super(message, cause);
+        this.lockCode = lockCode;
+        this.lockfilePath = lockfilePath;
+        this.name = 'SitesFileLockError';
+    }
+}
+/**
+ * Returns the empty seed used when a sites file does not yet exist.
+ * Callers (W3 registry) detect "no file → run env-bridge fallback".
+ */
+export function emptySitesFile() {
+    return { schema_version: 1, default_site_id: null, sites: [] };
+}
+/**
+ * Load + validate a sites file.
+ *
+ * Returns {@link emptySitesFile} when the path does not exist (no error).
+ * Throws {@link SchemaVersionError} for a known-unknown version and
+ * {@link SitesFileError} for JSON-parse or Zod-validation failures.
+ */
+export async function loadSitesFile(path) {
+    if (!existsSync(path)) {
+        return emptySitesFile();
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch (e) {
+        throw new SitesFileError(`Failed to read sites file at ${path}`, e);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new SitesFileError(`Sites file at ${path} is not valid JSON`, e);
+    }
+    if (typeof parsed === 'object' && parsed !== null
+        && 'schema_version' in parsed
+        && parsed.schema_version !== 1) {
+        throw new SchemaVersionError(parsed.schema_version);
+    }
+    const result = SitesFile.safeParse(parsed);
+    if (!result.success) {
+        throw new SitesFileError(`Sites file at ${path} failed schema validation: ` +
+            result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '));
+    }
+    return result.data;
+}
+/**
+ * Persist + validate a sites file atomically with chmod 0600.
+ *
+ * Pipeline:
+ *  1. Acquire `<path>.lock` via proper-lockfile (with retries).
+ *  2. Validate `data` through {@link SitesFile} (rejects bad input
+ *     before touching the filesystem).
+ *  3. Ensure parent directory exists.
+ *  4. Write JSON to `<path>.tmp.<pid>.<rand>`, fsync, chmod 0600.
+ *  5. `renameSync` over `<path>`.
+ *  6. Release lock.
+ *
+ * Tmp-file cleanup on any failure path.
+ */
+export async function saveSitesFile(path, data) {
+    const validated = SitesFile.safeParse(data);
+    if (!validated.success) {
+        throw new SitesFileError(`Refusing to write invalid sites file: ` +
+            validated.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '));
+    }
+    const dir = dirname(path);
+    // W12-R1.2 (A2-M3): the on-disk sites file ends up chmod 0600, but
+    // the parent directory was previously created with the process
+    // umask — typically 0o755 on Linux/macOS, which is world-readable.
+    // A world-readable parent dir is harmless for the bearers (they
+    // live in 0600 files) but DOES leak the existence of a sites.json
+    // to any local user. Tighten to 0700 (owner-only rwx) on creation.
+    // Existing directories are left as-is — mkdirSync is a no-op when
+    // the dir exists, and chmod'ing an existing dir would surprise
+    // operators who chose a shared location intentionally.
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // proper-lockfile defaults to realpath:true, which throws ENOENT for
+    // a not-yet-existing target. Disable realpath + steer the lock at an
+    // explicit sibling path. The lock dir always exists (mkdirSync above).
+    const lockfilePath = `${path}.lock`;
+    let release;
+    try {
+        release = await lockfile.lock(path, {
+            lockfilePath,
+            realpath: false,
+            stale: 10_000,
+            retries: { retries: 10, minTimeout: 50, maxTimeout: 500, factor: 2 },
+        });
+    }
+    catch (e) {
+        // W12-R1.2 (A4-F1): map the underlying error code into a
+        // discriminated lock-failure so callers can render the right
+        // recovery hint instead of telling the user three possible
+        // causes at once.
+        const errCode = e !== null && typeof e === 'object' && 'code' in e
+            ? e.code
+            : undefined;
+        let lockCode;
+        let hint;
+        if (errCode === 'ELOCKED') {
+            lockCode = 'LOCK_TIMEOUT';
+            hint =
+                'Another setup process is currently writing — retry in 30s.';
+        }
+        else if (errCode === 'EACCES' || errCode === 'EPERM') {
+            lockCode = 'LOCK_PERMISSION';
+            hint = `Cannot write to lock dir. Check permissions on ${dir}.`;
+        }
+        else {
+            lockCode = 'LOCK_ORPHAN';
+            hint =
+                `Stale lock from prior crashed process. Remove with: rm ${lockfilePath}`;
+        }
+        throw new SitesFileLockError(lockCode, lockfilePath, `Could not acquire lock on ${lockfilePath}. ${hint}`, e);
+    }
+    const tmpPath = `${path}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
+    try {
+        const fd = openSync(tmpPath, 'w', 0o600);
+        try {
+            const payload = JSON.stringify(validated.data, null, 2) + '\n';
+            writeSync(fd, payload);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        // Belt-and-braces: openSync's mode arg may be umask-clamped on
+        // some platforms; the explicit chmod guarantees 0600 regardless.
+        chmodSync(tmpPath, 0o600);
+        renameSync(tmpPath, path);
+    }
+    catch (e) {
+        // Best-effort tmp cleanup; ignore failures.
+        try {
+            if (existsSync(tmpPath))
+                unlinkSync(tmpPath);
+        }
+        catch { /* swallow */ }
+        throw new SitesFileError(`Failed to write sites file at ${path}`, e);
+    }
+    finally {
+        await release().catch(() => { });
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/sites/store.js.map

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

package/dist/sites/tools/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * W7 — sites/tools/ aggregator.
+ *
+ * Returns the two L1 platform-agnostic site-management tools:
+ *   - `yootheme_builder_sites_list`   (registry inspection — no REST)
+ *   - `yootheme_builder_sites_test`   (per-site connectivity probe)
+ *
+ * Wired into `buildAllTools(pool)` — the aggregator pulls the
+ * read-only `SiteRegistry` off the pool internally so callers thread
+ * only the pool through, never the registry separately.
+ *
+ * @license MIT
+ */
+import type { ClientPool } from '../client-pool.js';
+import type { AnyToolDefinition } from '../../tools/tool-builder.js';
+/**
+ * Build the W7 sites-management tool pair. The pool's read-only
+ * `registry` accessor feeds `buildSitesListTool` (which never resolves
+ * a bearer); the pool itself feeds `buildSitesTestTool` (which calls
+ * `pool.resolve(site_id)` to obtain a `RestClient`).
+ *
+ * W12-R1.3 (A1-L-01): single-arg signature — reading the registry off
+ * the pool inside this aggregator removes the only call-site that
+ * needed the pool's `registry` getter, so the getter can stay
+ * `@internal`.
+ */
+export declare function buildSitesTools(pool: ClientPool): readonly AnyToolDefinition[];
+//# sourceMappingURL=index.d.ts.map

package/dist/sites/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sites/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAMrE;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE,UAAU,GACjB,SAAS,iBAAiB,EAAE,CAS9B"}

package/dist/sites/tools/index.js

@@ -0,0 +1,38 @@
+/**
+ * W7 — sites/tools/ aggregator.
+ *
+ * Returns the two L1 platform-agnostic site-management tools:
+ *   - `yootheme_builder_sites_list`   (registry inspection — no REST)
+ *   - `yootheme_builder_sites_test`   (per-site connectivity probe)
+ *
+ * Wired into `buildAllTools(pool)` — the aggregator pulls the
+ * read-only `SiteRegistry` off the pool internally so callers thread
+ * only the pool through, never the registry separately.
+ *
+ * @license MIT
+ */
+import { buildSitesListTool } from './sites-list.js';
+import { buildSitesTestTool } from './sites-test.js';
+import { buildUseSiteTool } from './use-site.js';
+/**
+ * Build the W7 sites-management tool pair. The pool's read-only
+ * `registry` accessor feeds `buildSitesListTool` (which never resolves
+ * a bearer); the pool itself feeds `buildSitesTestTool` (which calls
+ * `pool.resolve(site_id)` to obtain a `RestClient`).
+ *
+ * W12-R1.3 (A1-L-01): single-arg signature — reading the registry off
+ * the pool inside this aggregator removes the only call-site that
+ * needed the pool's `registry` getter, so the getter can stay
+ * `@internal`.
+ */
+export function buildSitesTools(pool) {
+    return [
+        buildSitesListTool(pool.registry),
+        buildSitesTestTool(pool),
+        // Phase 3 — runtime active-site switch (mirrors api-mapper's
+        // `apimapper_use_profile`). Reuses the pool's in-memory active-
+        // site override; never rebuilds the multi-site engine.
+        buildUseSiteTool(pool),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/sites/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sites/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC3B,IAAgB;IAEhB,OAAO;QACH,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC;QACjC,kBAAkB,CAAC,IAAI,CAAC;QACxB,6DAA6D;QAC7D,gEAAgE;QAChE,uDAAuD;QACvD,gBAAgB,CAAC,IAAI,CAAC;KACzB,CAAC;AACN,CAAC"}

package/dist/sites/tools/sites-list.d.ts

@@ -0,0 +1,48 @@
+/**
+ * W7 — `yootheme_builder_sites_list` L1 tool.
+ *
+ * Platform-agnostic registry inspection: lists the in-process
+ * {@link SiteRegistry} as a tabular result so an agent (or a Maria-class
+ * Claude-Desktop user) can discover which site_ids are wired into this
+ * MCP server WITHOUT a network round-trip.
+ *
+ * Why it does NOT call `pool.resolve()`:
+ *  - The tool reads the registry verbatim and never touches bearers, the
+ *    secret-resolver, or any HTTP endpoint. Resolving through the pool
+ *    would force a default-site requirement that is exactly the
+ *    bootstrap failure-mode the tool is meant to diagnose ("I added
+ *    sites but forgot to mark a default"). For the same reason the
+ *    handler intentionally skips `withSiteMeta` — there is no resolved
+ *    site to stamp; instead we emit a `structuredContent._meta.tool_kind
+ *    = 'registry'` marker so MCP hosts can route the result through a
+ *    registry-aware UI if/when they grow one.
+ *
+ * Why `site_id` is exposed but unused:
+ *  - The W5 SITE_ID_SCHEMA pin requires EVERY tool to expose the
+ *    optional `site_id` field so legacy/scripted callers never trip a
+ *    Zod parse on an extra-property. The W12-R1.3 DESCRIPTION_SUFFIX_EXEMPT
+ *    list opts this tool out of the canonical description suffix
+ *    because "operates on the default site" would imply per-row
+ *    filtering that the handler does not perform.
+ *
+ * W12-R1.3 (A2-L4): `bearer_source` was previously projected into the
+ *  output row + table column. Even though it carried only the literal
+ *  `'plain'` / `'op'`, the `sites://current` resource already omits
+ *  this field (see ADR rationale in server.ts) and the tool surface
+ *  should match for cross-surface consistency. The field is dropped
+ *  from both the structured row AND the table column.
+ *
+ * @license MIT
+ */
+import type { SiteRegistry } from '../registry.js';
+import { type AnyToolDefinition } from '../../tools/tool-builder.js';
+/**
+ * Build the W7 `yootheme_builder_sites_list` tool.
+ *
+ * Signature accepts the {@link SiteRegistry} directly — unlike other
+ * tool-builders, it does NOT need the {@link ClientPool} because it
+ * never resolves a site. Callers wire `buildSitesListTool(pool.registry)`
+ * from the W7 aggregator (`src/sites/tools/index.ts`).
+ */
+export declare function buildSitesListTool(registry: SiteRegistry): AnyToolDefinition;
+//# sourceMappingURL=sites-list.d.ts.map

package/dist/sites/tools/sites-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites-list.d.ts","sourceRoot":"","sources":["../../../src/sites/tools/sites-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAIH,KAAK,iBAAiB,EACzB,MAAM,6BAA6B,CAAC;AA+BrC;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,iBAAiB,CAqE5E"}