@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

package/dist/catalog/build-catalog.js

@@ -1,133 +1,11 @@
-/**
- * packages/mcp/src/catalog/build-catalog.ts — net-new (Slice 0b Task 12).
- *
- * Builds the machine-readable tool catalogue (SSOT for the PHP-served MCP
- * surface). Modelled on API Mapper's
- * `packages/apimapper-mcp/src/catalog/build-catalog.ts`, adapted to yt-builder's
- * `buildAllTools(pool)` entrypoint:
- *
- *  - yt-builder's tools carry `inputSchema` as a RAW Zod shape (ZodRawShape,
- *    no `_zod` marker), so `toJsonSchema` always takes the raw-shape branch
- *    (`z.object(inputSchema)`).
- *  - `tier` is derived per-name from the gateway essentials lists
- *    (`isEssential || isDirectTopLevel` ⇒ essential, else advanced). There is
- *    NO separate advanced registry to query.
- *  - The 32 catalogued tools are exactly what `buildAllTools` returns; the two
- *    top-level gateways are registered at server level (server.ts), not here.
- *
- * @license MIT
- */
-import { z } from 'zod';
 import { buildAllTools } from '../tools/index.js';
+import { shippedOutputSchema } from '../server.js';
+import { toJsonSchema } from './json-schema.js';
 import { isEssential, isDirectTopLevel } from '../gateway/essentials.js';
 import { SiteRegistry } from '../sites/registry.js';
 import { ClientPool } from '../sites/client-pool.js';
 import { PlainSecretResolver } from '../sites/secret-resolver.js';
-/**
- * Convert a tool inputSchema to JSON Schema. yt-builder tools yield a RAW Zod
- * shape (ZodRawShape) — the `_zod` guard keeps this a faithful port of the
- * API Mapper utility, but for this server the raw-shape branch
- * (`z.object(inputSchema)`) is the one that always fires. Native
- * `z.toJSONSchema` (zod 4).
- */
-export function toJsonSchema(inputSchema) {
-    try {
-        if (inputSchema && typeof inputSchema === 'object') {
-            const isZodObject = '_zod' in inputSchema;
-            const schema = isZodObject
-                ? inputSchema
-                : z.object(inputSchema);
-            const json = z.toJSONSchema(schema);
-            normalizeJsonSchema(json);
-            return json;
-        }
-    }
-    catch {
-        /* malformed/unsupported shape → safe fallback */
-    }
-    return { type: 'object' };
-}
-/**
- * Post-process a generated JSON Schema for MCP-client compatibility + semantic
- * correctness, recursively at EVERY schema node. Two structural fixes:
- *
- *  A1 (#4): drop from a node's `required` array any property that carries a
- *  `default`. Zod `.default()` lands the key in `required` (a zod4 toJSONSchema
- *  quirk), but a field WITH a default is semantically OPTIONAL — advertising it
- *  as required makes a strict client (and the PHP gateway validator) reject a
- *  call that legitimately omits it.
- *
- *  A2 (#1): replace an EMPTY-object `additionalProperties: {}` (what
- *  z.record(z.string(), z.unknown()) emits) with `true`. The Anthropic client
- *  rejects an empty `{}` schema for additionalProperties; `true` is the
- *  faithful "any value" equivalent. A boolean `false`
- *  (z.object().strict()) is left untouched.
- *
- * Recurses through every schema-bearing position zod4 emits: `properties`
- * values, `items` (object or tuple array), an object-valued
- * `additionalProperties`, and the `oneOf`/`anyOf`/`allOf`/`prefixItems` branch
- * arrays.
- */
-export function normalizeJsonSchema(node) {
-    if (Array.isArray(node)) {
-        for (const child of node)
-            normalizeJsonSchema(child);
-        return;
-    }
-    if (!node || typeof node !== 'object')
-        return;
-    const obj = node;
-    // A2: empty-object additionalProperties → true (recurse into a non-empty one).
-    if ('additionalProperties' in obj) {
-        const ap = obj.additionalProperties;
-        if (ap &&
-            typeof ap === 'object' &&
-            !Array.isArray(ap) &&
-            Object.keys(ap).length === 0) {
-            obj.additionalProperties = true;
-        }
-        else {
-            normalizeJsonSchema(ap);
-        }
-    }
-    // A1: drop default-bearing keys from THIS node's `required`.
-    const props = obj.properties;
-    if (Array.isArray(obj.required) && props && typeof props === 'object') {
-        const propMap = props;
-        const kept = obj.required.filter((key) => {
-            if (typeof key !== 'string')
-                return true;
-            const p = propMap[key];
-            return !(p && typeof p === 'object' && 'default' in p);
-        });
-        // An emptied required array is dropped (zod itself omits an empty `required`).
-        if (kept.length === 0)
-            delete obj.required;
-        else
-            obj.required = kept;
-    }
-    // Recurse into the standard schema-bearing positions.
-    if (props && typeof props === 'object') {
-        for (const v of Object.values(props)) {
-            normalizeJsonSchema(v);
-        }
-    }
-    if ('items' in obj)
-        normalizeJsonSchema(obj.items);
-    for (const kw of ['oneOf', 'anyOf', 'allOf', 'prefixItems']) {
-        if (kw in obj)
-            normalizeJsonSchema(obj[kw]);
-    }
-}
-/**
- * One-site, in-memory, zero-IO {@link ClientPool}. Mirrors the stub
- * `scripts/extract-tools.mjs` wires (a single `wordpress` site with an inline
- * stub bearer), but importing the classes from `src/sites/*` rather than the
- * compiled `dist/index.js` barrel. `buildAllTools` only reads `pool.registry`
- * for tool registration and never resolves a bearer or hits the network at
- * catalogue-build time.
- */
-function stubPool() {
+export function stubPool() {
     const stubFile = {
         schema_version: 1,
         default_site_id: 'build-catalog-stub',
@@ -145,12 +23,23 @@ function stubPool() {
     const resolver = new PlainSecretResolver();
     return new ClientPool(registry, resolver);
 }
+export function withErrorBranch(schema) {
+    const { $schema, type, ...rest } = schema;
+    return {
+        ...($schema !== undefined ? { $schema } : {}),
+        ...(type !== undefined ? { type } : {}),
+        anyOf: [rest, { required: ['error'] }],
+    };
+}
 export async function buildCatalog() {
-    const tools = buildAllTools(stubPool()); // flat AnyToolDefinition[] — 32 entries
+    const tools = buildAllTools(stubPool());
     const catalogTools = tools.map((t) => ({
         name: t.name,
         description: t.description ?? '',
         jsonSchema: toJsonSchema(t.inputSchema),
+        ...(t.outputSchema !== undefined
+            ? { outputJsonSchema: withErrorBranch(toJsonSchema(shippedOutputSchema(t))) }
+            : {}),
         annotations: t.annotations ?? {},
         tier: isEssential(t.name) || isDirectTopLevel(t.name) ? 'essential' : 'advanced',
     }));

package/dist/catalog/build-catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-catalog.js","sourceRoot":"","sources":["../../src/catalog/build-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build-catalog.js","sourceRoot":"","sources":["../../src/catalog/build-catalog.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AA4DlE,MAAM,UAAU,QAAQ;IACpB,MAAM,QAAQ,GAAG;QACb,cAAc,EAAE,CAAU;QAC1B,eAAe,EAAE,oBAAoB;QACrC,KAAK,EAAE;YACH;gBACI,OAAO,EAAE,oBAAoB;gBAC7B,GAAG,EAAE,qBAAqB;gBAC1B,QAAQ,EAAE,WAAoB;gBAC9B,MAAM,EAAE,oBAAoB;gBAC5B,UAAU,EAAE,IAAI;aACnB;SACJ;KACJ,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,mBAAmB,EAAE,CAAC;IAC3C,OAAO,IAAI,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAiCD,MAAM,UAAU,eAAe,CAAC,MAAc;IAC1C,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,MAA+C,CAAC;IAOnF,OAAO;QACH,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;KACzC,CAAC;AACN,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IAC9B,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC;IACxC,MAAM,YAAY,GAAkB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE;QAChC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;QAQvC,GAAG,CAAC,CAAC,CAAC,YAAY,KAAK,SAAS;YAC5B,CAAC,CAAC,EAAE,gBAAgB,EAAE,eAAe,CAAC,YAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE;YAC7E,CAAC,CAAC,EAAE,CAAC;QACT,WAAW,EAAG,CAAC,CAAC,WAAuC,IAAI,EAAE;QAC7D,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU;KACnF,CAAC,CAAC,CAAC;IACJ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAClF,CAAC;IACD,OAAO;QACH,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO;QACnD,aAAa,EAAE,KAAK;QACpB,KAAK,EAAE,YAAY;KACtB,CAAC;AACN,CAAC"}

package/dist/catalog/json-schema.d.ts

@@ -0,0 +1,3 @@
+export declare function toJsonSchema(inputSchema: unknown): object;
+export declare function normalizeJsonSchema(node: unknown): void;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/catalog/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/catalog/json-schema.ts"],"names":[],"mappings":"AA0BA,wBAAgB,YAAY,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CA8BzD;AAuBD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CA+CvD"}

package/dist/catalog/json-schema.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export function toJsonSchema(inputSchema) {
+    try {
+        if (inputSchema && typeof inputSchema === 'object') {
+            const isZodObject = '_zod' in inputSchema;
+            const schema = isZodObject
+                ? inputSchema
+                : z.object(inputSchema);
+            const json = z.toJSONSchema(schema);
+            normalizeJsonSchema(json);
+            if (json.additionalProperties !== true) {
+                json.additionalProperties = false;
+            }
+            return json;
+        }
+    }
+    catch {
+    }
+    return { type: 'object' };
+}
+export function normalizeJsonSchema(node) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            normalizeJsonSchema(child);
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    const obj = node;
+    if ('additionalProperties' in obj) {
+        const ap = obj.additionalProperties;
+        if (ap &&
+            typeof ap === 'object' &&
+            !Array.isArray(ap) &&
+            Object.keys(ap).length === 0) {
+            obj.additionalProperties = true;
+        }
+        else {
+            normalizeJsonSchema(ap);
+        }
+    }
+    const props = obj.properties;
+    if (Array.isArray(obj.required) && props && typeof props === 'object') {
+        const propMap = props;
+        const kept = obj.required.filter((key) => {
+            if (typeof key !== 'string')
+                return true;
+            const p = propMap[key];
+            return !(p && typeof p === 'object' && 'default' in p);
+        });
+        if (kept.length === 0)
+            delete obj.required;
+        else
+            obj.required = kept;
+    }
+    if (props && typeof props === 'object') {
+        for (const v of Object.values(props)) {
+            normalizeJsonSchema(v);
+        }
+    }
+    if ('items' in obj)
+        normalizeJsonSchema(obj.items);
+    for (const kw of ['oneOf', 'anyOf', 'allOf', 'prefixItems']) {
+        if (kw in obj)
+            normalizeJsonSchema(obj[kw]);
+    }
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/catalog/json-schema.js.map

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

package/dist/catalog/output-shapes.d.ts

@@ -0,0 +1,6 @@
+export interface OutputShapes {
+    readonly generatedFrom: 'zod';
+    readonly tools: Record<string, readonly string[]>;
+}
+export declare function buildOutputShapes(): OutputShapes;
+//# sourceMappingURL=output-shapes.d.ts.map

package/dist/catalog/output-shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-shapes.d.ts","sourceRoot":"","sources":["../../src/catalog/output-shapes.ts"],"names":[],"mappings":"AAoKA,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC;IAE9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACrD;AAOD,wBAAgB,iBAAiB,IAAI,YAAY,CAYhD"}

package/dist/catalog/output-shapes.js

@@ -0,0 +1,89 @@
+import { buildAllTools } from '../tools/index.js';
+import { shippedOutputSchema } from '../server.js';
+import { stubPool } from './build-catalog.js';
+const ARRAY_HOP = '[]';
+const RECORD_HOP = '{}';
+const MAX_DEPTH = 14;
+const TRANSPARENT = new Set([
+    'optional',
+    'nullable',
+    'default',
+    'readonly',
+    'nonoptional',
+    'catch',
+    'prefault',
+]);
+function defOf(node) {
+    return node?._zod?.def ?? null;
+}
+function walk(node, pfad, tiefe, out) {
+    if (tiefe > MAX_DEPTH)
+        return;
+    const def = defOf(node);
+    if (def === null)
+        return;
+    const t = def.type ?? '';
+    if (TRANSPARENT.has(t)) {
+        walk(def.innerType, pfad, tiefe + 1, out);
+        return;
+    }
+    if (t === 'record') {
+        if (pfad.length > 0)
+            out.add(pfad.join('/'));
+        walk(def.valueType, [...pfad, RECORD_HOP], tiefe + 1, out);
+        return;
+    }
+    if (t === 'object') {
+        if (pfad.length > 0)
+            out.add(pfad.join('/'));
+        for (const [key, child] of Object.entries(def.shape ?? {})) {
+            if (key.includes('/'))
+                continue;
+            walk(child, [...pfad, key], tiefe + 1, out);
+        }
+        return;
+    }
+    if (t === 'array') {
+        walk(def.element, [...pfad, ARRAY_HOP], tiefe + 1, out);
+        return;
+    }
+    if (t === 'tuple') {
+        for (const slot of def.items ?? [])
+            walk(slot, [...pfad, ARRAY_HOP], tiefe + 1, out);
+        return;
+    }
+    if (t === 'union') {
+        for (const option of def.options ?? [])
+            walk(option, pfad, tiefe + 1, out);
+        return;
+    }
+    if (t === 'intersection') {
+        walk(def.left, pfad, tiefe + 1, out);
+        walk(def.right, pfad, tiefe + 1, out);
+        return;
+    }
+    if (t === 'pipe') {
+        walk(def.out ?? def.in, pfad, tiefe + 1, out);
+        return;
+    }
+    if (t === 'lazy') {
+        const getter = def.getter;
+        if (typeof getter === 'function')
+            walk(getter(), pfad, tiefe + 1, out);
+    }
+}
+export function buildOutputShapes() {
+    const tools = {};
+    for (const tool of buildAllTools(stubPool())) {
+        const schema = shippedOutputSchema(tool);
+        if (schema === undefined)
+            continue;
+        const found = new Set();
+        walk(schema, [], 0, found);
+        if (found.size === 0)
+            continue;
+        tools[tool.name] = [...found].sort();
+    }
+    return { generatedFrom: 'zod', tools };
+}
+//# sourceMappingURL=output-shapes.js.map

package/dist/catalog/output-shapes.js.map

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

package/dist/catalog/tool-catalog-markdown.d.ts

@@ -1,31 +1,3 @@
-/**
- * packages/mcp/src/catalog/tool-catalog-markdown.ts — Behavior-Truth ④.
- *
- * The SINGLE source of truth for the SKILL.md "Tool Catalog" appendix
- * Markdown. Previously this rendering logic lived ONLY inline in
- * `scripts/extract-tools.mjs`, so nothing could re-derive the appendix to
- * assert it stayed fresh — a tool description could drift from the committed
- * appendix and every test stayed green (the render_preview/A6 stale-row proved
- * it live).
- *
- * Now BOTH consumers import this one pure function:
- *   - `scripts/extract-tools.mjs` (the generator) — via the compiled
- *     `dist/index.js` re-export.
- *   - `tests/skills/skill-md-behavior-truth.test.ts` (the freshness gate) —
- *     re-renders from the live `buildAllTools()` registry and byte-compares
- *     against the committed appendix block.
- *
- * Because there is exactly ONE renderer, the generated appendix and the
- * freshness assertion can never disagree about the row format. The output is
- * byte-identical to the prior inline implementation.
- *
- * @license MIT
- */
-/**
- * The minimal tool metadata the catalog row needs. `buildAllTools()` returns
- * `AnyToolDefinition[]`, which is structurally assignable to this — kept as a
- * decoupled structural type so the renderer stays pure and dependency-free.
- */
 export interface CatalogToolEntry {
     readonly name: string;
     readonly description: string;
@@ -37,19 +9,11 @@ export interface CatalogToolEntry {
         readonly openWorldHint?: boolean;
     };
 }
-/** Split counts the header line derives from the gateway source-of-truth. */
 export interface CatalogCounts {
-    /** `ESSENTIAL_TOOLS.length` — the L1 forwarded essentials. */
     readonly essentialCount: number;
-    /** `DIRECT_TOP_LEVEL_TOOLS.length` — the L3 direct top-level tools. */
     readonly directCount: number;
-    /** Top-level gateways advertised in `tools/list` (write + read-only). */
     readonly gatewayCount?: number;
 }
-/**
- * Render the deterministic tool-catalog Markdown (header line + table) for the
- * SKILL.md appendix. Pure: identical input ⇒ identical bytes. The trailing
- * newline matches the generator's `lines.join('\n') + '\n'` contract.
- */
+export declare function describeToolKind(annotations: CatalogToolEntry['annotations'] | null | undefined): string;
 export declare function renderToolCatalogMarkdown(tools: readonly CatalogToolEntry[], counts: CatalogCounts): string;
 //# sourceMappingURL=tool-catalog-markdown.d.ts.map

package/dist/catalog/tool-catalog-markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-catalog-markdown.d.ts","sourceRoot":"","sources":["../../src/catalog/tool-catalog-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE;QAClB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;KACpC,CAAC;CACL;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAClC;AAiCD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACrC,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAClC,MAAM,EAAE,aAAa,GACtB,MAAM,CA2CR"}
+{"version":3,"file":"tool-catalog-markdown.d.ts","sourceRoot":"","sources":["../../src/catalog/tool-catalog-markdown.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE;QAClB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;QACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;KACpC,CAAC;CACL;AAGD,MAAM,WAAW,aAAa;IAE1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAClC;AAiED,wBAAgB,gBAAgB,CAC5B,WAAW,EAAE,gBAAgB,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,GAChE,MAAM,CAER;AAeD,wBAAgB,yBAAyB,CACrC,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAClC,MAAM,EAAE,aAAa,GACtB,MAAM,CA2CR"}

package/dist/catalog/tool-catalog-markdown.js

@@ -1,57 +1,26 @@
-/**
- * packages/mcp/src/catalog/tool-catalog-markdown.ts — Behavior-Truth ④.
- *
- * The SINGLE source of truth for the SKILL.md "Tool Catalog" appendix
- * Markdown. Previously this rendering logic lived ONLY inline in
- * `scripts/extract-tools.mjs`, so nothing could re-derive the appendix to
- * assert it stayed fresh — a tool description could drift from the committed
- * appendix and every test stayed green (the render_preview/A6 stale-row proved
- * it live).
- *
- * Now BOTH consumers import this one pure function:
- *   - `scripts/extract-tools.mjs` (the generator) — via the compiled
- *     `dist/index.js` re-export.
- *   - `tests/skills/skill-md-behavior-truth.test.ts` (the freshness gate) —
- *     re-renders from the live `buildAllTools()` registry and byte-compares
- *     against the committed appendix block.
- *
- * Because there is exactly ONE renderer, the generated appendix and the
- * freshness assertion can never disagree about the row format. The output is
- * byte-identical to the prior inline implementation.
- *
- * @license MIT
- */
-/**
- * Derive the `Kind` column from the MCP annotation hints. Mirrors the prior
- * inline logic exactly: read flag → 'read', plus destructive / idempotent /
- * openWorld; no flags at all ⇒ 'mutating'.
- */
 function describeAnnotations(a) {
     if (a === null || a === undefined || typeof a !== 'object')
-        return 'read';
-    const flags = [];
-    if (a.readOnlyHint === true)
-        flags.push('read');
+        return 'unannotated';
+    const flags = [a.readOnlyHint === true ? 'read' : 'write'];
     if (a.destructiveHint === true)
         flags.push('destructive');
     if (a.idempotentHint === true)
         flags.push('idempotent');
+    else if (a.idempotentHint === false)
+        flags.push('non-idempotent');
     if (a.openWorldHint === true)
         flags.push('openWorld');
-    return flags.length === 0 ? 'mutating' : flags.join('+');
+    return flags.join('+');
+}
+export function describeToolKind(annotations) {
+    return describeAnnotations(annotations);
 }
-/** The sorted input-key list for the `Input keys` column. */
 function listInputKeys(schema) {
     if (schema === null || schema === undefined || typeof schema !== 'object') {
         return [];
     }
     return Object.keys(schema).sort();
 }
-/**
- * Render the deterministic tool-catalog Markdown (header line + table) for the
- * SKILL.md appendix. Pure: identical input ⇒ identical bytes. The trailing
- * newline matches the generator's `lines.join('\n') + '\n'` contract.
- */
 export function renderToolCatalogMarkdown(tools, counts) {
     const records = tools
         .map((t) => ({
@@ -67,18 +36,6 @@ export function renderToolCatalogMarkdown(tools, counts) {
     const advertised = l1 + l3 + gateway;
     const advanced = records.length - l1 - l3;
     const callable = records.length + gateway;
-    // Each count is rendered in the ROLE it actually has, and the sum on the
-    // left of the `=` is the one that balances:
-    //   catalogued + gateways      = callable    (everything dispatchable)
-    //   L1 + L3 + gateways         = advertised  (what `tools/list` shows)
-    //   advertised + advanced      = callable    (the gateway lane is the rest)
-    // The shipped header once put `callable` in the `tools/list` slot ("55
-    // reachable via `tools/list`") next to "42 advertised" in the same
-    // sentence — `tools/list` advertises 42 and the 13 gateway-routed tools are
-    // exactly the ones it does NOT list. Pinned by
-    // `tool-catalog-markdown.test.ts` with a fixture where advertised !=
-    // callable, because appendix-freshness byte-compares against THIS renderer
-    // and would happily re-bless a wrong header.
     const lines = [
         `**${records.length} catalogued tools** plus the \`yootheme_builder_advanced\` (write) + \`yootheme_builder_advanced_read\` (read-only) gateways = **${callable} callable** end to end, of which **${advertised} are advertised in \`tools/list\`** (${l1} L1 + ${l3} L3 + ${gateway} gateways); the remaining ${advanced} advanced tools are reachable only through the gateways. Generated by \`scripts/extract-tools.mjs\` from the compiled \`buildAllTools()\` registry. Do not hand-edit this section; re-run \`npm run build && node scripts/extract-tools.mjs\` after changing tool definitions.`,
         '',
@@ -87,7 +44,6 @@ export function renderToolCatalogMarkdown(tools, counts) {
     ];
     for (const r of records) {
         const keys = r.inputKeys.length === 0 ? '_(none)_' : '`' + r.inputKeys.join('`, `') + '`';
-        // Escape pipe chars in the description so the table doesn't break.
         const desc = r.description.replace(/\|/g, '\\|');
         lines.push(`| \`${r.name}\` | ${r.kind} | ${keys} | ${desc} |`);
     }

package/dist/catalog/tool-catalog-markdown.js.map

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

package/dist/cli/doctor-command.d.ts

@@ -2,20 +2,15 @@ import { type DoctorDeps } from '../diagnostics/doctor.js';
 interface ParsedDoctorArgs {
     url?: string;
     token?: string;
+    help?: boolean;
 }
-/** Parse `--url <x> --token <y>` from the doctor argv tail. */
 export declare function parseDoctorArgs(argv: readonly string[]): ParsedDoctorArgs;
+export declare const DOCTOR_HELP_TEXT: string;
 export interface DoctorCommandDeps {
     deps?: DoctorDeps;
     log?: (line: string) => void;
     env?: NodeJS.ProcessEnv;
 }
-/**
- * `yt-builder-mcp doctor [--url <site> --token <key>]` — run the self-diagnostic
- * and print an actionable report. Falls back to YTB_MCP_SITE_URL /
- * YTB_MCP_BEARER_TOKEN when the flags are omitted (so it works against an
- * already-configured server entry). Returns 0 when all critical checks pass.
- */
 export declare function doctorCommand(argv: readonly string[], overrides?: DoctorCommandDeps): Promise<number>;
 export {};
 //# sourceMappingURL=doctor-command.d.ts.map

package/dist/cli/doctor-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor-command.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-command.ts"],"names":[],"mappings":"AAIA,OAAO,EAKH,KAAK,UAAU,EAGlB,MAAM,0BAA0B,CAAC;AAmFlC,UAAU,gBAAgB;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAczE;AA+FD,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB/G"}
+{"version":3,"file":"doctor-command.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-command.ts"],"names":[],"mappings":"AAIA,OAAO,EAKH,KAAK,UAAU,EAGlB,MAAM,0BAA0B,CAAC;AAmFlC,UAAU,gBAAgB;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IASf,IAAI,CAAC,EAAE,OAAO,CAAC;CAClB;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAgBzE;AAGD,eAAO,MAAM,gBAAgB,EAAE,MAWnB,CAAC;AA+Fb,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC3B;AAQD,wBAAsB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,GAAE,iBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B/G"}