@wootsup/yt-builder-mcp 1.0.0 → 1.1.0

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;AAKrE;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE,UAAU,GACjB,SAAS,iBAAiB,EAAE,CAE9B"}

package/dist/sites/tools/index.js

@@ -0,0 +1,30 @@
+/**
+ * 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';
+/**
+ * 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)];
+}
+//# 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;AAErD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC3B,IAAgB;IAEhB,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AACzE,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,CAmE5E"}

package/dist/sites/tools/sites-list.js

@@ -0,0 +1,135 @@
+/**
+ * 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 { tableResult } from '@getimo/mcp-toolkit';
+import { z } from 'zod';
+import { SITE_ID_SCHEMA } from '../../tools/shared-schemas.js';
+import { defineTool, readOnly, structuredResult, } from '../../tools/tool-builder.js';
+const SITES_LIST_OUTPUT_SCHEMA = z.object({
+    items: z.array(z.object({
+        site_id: z.string(),
+        url: z.string(),
+        platform_hint: z.enum(['wordpress', 'joomla', 'auto']),
+        platform_resolved: z.enum(['wordpress', 'joomla']).optional(),
+        is_default: z.boolean(),
+        label: z.string().optional(),
+    })),
+    total: z.number(),
+    default_site_id: z.string().nullable(),
+    _meta: z
+        .object({
+        tool_kind: z.string(),
+    })
+        .passthrough()
+        .optional(),
+});
+const TABLE_COLUMNS = [
+    { key: 'site_id', label: 'SITE_ID', width: 20 },
+    { key: 'url', label: 'URL', width: 36 },
+    { key: 'platform', label: 'PLATFORM', width: 11 },
+    { key: 'is_default', label: 'DEFAULT', width: 9 },
+    { key: 'label', label: 'LABEL', width: 24 },
+];
+/**
+ * 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 function buildSitesListTool(registry) {
+    return defineTool({
+        name: 'yootheme_builder_sites_list',
+        description: 'List sites configured in this MCP server (site_id, URL, ' +
+            'platform, default flag). Read-only, no REST calls. ' +
+            'Discover site_ids before targeting one. ' +
+            '(site_id is accepted for schema-uniformity but ignored ' +
+            'by this tool.)',
+        inputSchema: {
+            site_id: SITE_ID_SCHEMA,
+        },
+        outputSchema: SITES_LIST_OUTPUT_SCHEMA,
+        annotations: readOnly('Sites — List configured'),
+        handler: async () => {
+            const rows = registry.listForDisplay();
+            const defaultSiteId = registry.defaultSiteId();
+            // Map the registry row to a structured-content item with
+            // safe-to-render primitives ONLY (no bearer leakage). The
+            // `platform` projection collapses hint + resolved into a
+            // single display string so the table stays readable.
+            const items = rows.map((row) => ({
+                site_id: row.site_id,
+                url: row.url,
+                platform_hint: row.platform_hint,
+                ...(row.platform_resolved !== undefined
+                    ? { platform_resolved: row.platform_resolved }
+                    : {}),
+                is_default: row.is_default,
+                ...(row.label !== undefined ? { label: row.label } : {}),
+            }));
+            // Table-side projection: humans see one `platform` column
+            // (resolved if known, hint otherwise) and a yes/no on
+            // is_default for legibility.
+            const tableRows = rows.map((row) => ({
+                site_id: row.site_id,
+                url: row.url,
+                platform: row.platform_resolved ?? row.platform_hint,
+                is_default: row.is_default ? 'yes' : 'no',
+                label: row.label ?? '',
+            }));
+            const toolkitResult = tableResult(tableRows, {
+                columns: TABLE_COLUMNS,
+                header: (count) => `${String(count)} configured site${count === 1 ? '' : 's'}` +
+                    (defaultSiteId !== null ? ` (default: ${defaultSiteId})` : ' (no default configured)'),
+                footer: 'Use yootheme_builder_sites_test <site_id> to verify connectivity. ' +
+                    'Pass `site_id: "<id>"` on any tool call to target a specific site.',
+            });
+            // The W6 `withSiteMeta` wrapper is intentionally NOT used —
+            // see the file header for rationale. We emit a stable
+            // `_meta.tool_kind: "registry"` marker so MCP hosts can
+            // distinguish registry tools from site-bound tools without
+            // string-matching the tool name.
+            return structuredResult(toolkitResult, {
+                items,
+                total: items.length,
+                default_site_id: defaultSiteId,
+                _meta: { tool_kind: 'registry' },
+            });
+        },
+    });
+}
+//# sourceMappingURL=sites-list.js.map

package/dist/sites/tools/sites-list.js.map

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

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

@@ -0,0 +1,47 @@
+/**
+ * W7 — `yootheme_builder_sites_test` L1 tool.
+ *
+ * Targeted connectivity probe for ONE site_id: runs `/health` (no auth
+ * required) + `/etag` (auth required) in parallel and returns a
+ * structured `{plugin_reachable, bearer_valid, platform, ...}` block.
+ *
+ * Why `site_id` is REQUIRED here (not optional):
+ *  - Every other tool in the registry treats `site_id` as an optional
+ *    selector that falls back to the default. `sites_test` is the
+ *    exception: its raison d'être is to verify ONE specific id, so the
+ *    schema upgrades from `.optional()` to required. The W5
+ *    SITE_ID_SCHEMA pin-test in `tests/tools/site-id-schema.test.ts`
+ *    explicitly skips this tool from its "every tool's site_id is
+ *    optional" loop — see the SITES_TEST_EXEMPT_FROM_OPTIONAL set there.
+ *
+ * Why the result wraps `withSiteMeta`:
+ *  - Once `pool.resolve(site_id)` succeeds we DO have a resolved-site
+ *    descriptor, so the text-prefix `[<label> @ <host>] ` is the same
+ *    site-awareness signal a Maria-class user already sees on every
+ *    other tool. The W6.2 wrapper handles both green AND red results
+ *    uniformly (it just stamps; no behaviour difference).
+ *
+ * Failure modes mapped:
+ *  - `UnknownSiteError` → structured error `code: 'unknown_site'` with
+ *    `available[]` hint (via `resolveSiteOrError`).
+ *  - `NoDefaultSiteError` → cannot fire here because site_id is required
+ *    and validated by Zod before the handler runs; left in the helper
+ *    for defense-in-depth.
+ *  - `/health` rejects → `plugin_reachable: false` + error message.
+ *  - `/etag` 401/403 → `plugin_reachable: true` + `bearer_valid: false`.
+ *  - `/etag` other reject → `plugin_reachable: true` + `bearer_valid:
+ *    false` + raw error.
+ *
+ * @license MIT
+ */
+import { type AnyToolDefinition } from '../../tools/tool-builder.js';
+import type { ClientPool } from '../client-pool.js';
+/**
+ * Build the W7 `yootheme_builder_sites_test` tool.
+ *
+ * Signature accepts the {@link ClientPool} directly (no separate
+ * registry param) — `pool.resolve(site_id)` is the single source of
+ * truth and carries the registry inside.
+ */
+export declare function buildSitesTestTool(pool: ClientPool): AnyToolDefinition;
+//# sourceMappingURL=sites-test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sites-test.d.ts","sourceRoot":"","sources":["../../../src/sites/tools/sites-test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAQH,OAAO,EAKH,KAAK,iBAAiB,EACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AA2BpD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CA0DtE"}