@ng-solid/mcp 22.0.0

package/lib/tools.components.js

@@ -0,0 +1,836 @@
+/**
+ * Discovery, API, form-control, service/provider and style-validation tools -- the bulk of
+ * the ng-solid MCP surface. Split out of `tools.ts` to keep that file a thin aggregator.
+ */
+import { z } from 'zod';
+import { jsonResult, loadSnapshot, textResult } from './data.js';
+import { parseTemplateCandidates } from './template-parser.js';
+import { validateStyleContract } from './style-contract.js';
+// ---------------------------------------------------------------------------
+// Shared helpers -- exported for reuse by tools.tokens.ts, tools.icons.ts,
+// tools.guides.ts, resources.ts and prompts.ts.
+// ---------------------------------------------------------------------------
+export function jsonError(payload) {
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify(payload, null, 2) }
+        ],
+        isError: true
+    };
+}
+export function importTrio(component) {
+    return {
+        selector: component.selector,
+        importStatement: `import { ${component.className} } from '${component.importFrom}';`,
+        imports: [component.className]
+    };
+}
+/** Plain Levenshtein edit distance, used to rank "did you mean" suggestions. */
+export function levenshtein(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const distances = Array.from({ length: rows }, (_row, i) => {
+        const line = new Array(cols).fill(0);
+        line[0] = i;
+        return line;
+    });
+    for (let j = 0; j < cols; j++)
+        distances[0][j] = j;
+    for (let i = 1; i < rows; i++) {
+        for (let j = 1; j < cols; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            distances[i][j] = Math.min(distances[i - 1][j] + 1, distances[i][j - 1] + 1, distances[i - 1][j - 1] + cost);
+        }
+    }
+    return distances[rows - 1][cols - 1];
+}
+export function suggestComponents(snapshot, query, limit = 5) {
+    const q = query
+        .trim()
+        .toLowerCase()
+        .replace(/^ns-/, '')
+        .replace(/^\[|\]$/g, '');
+    const scored = snapshot.components.map((c) => {
+        const bare = c.selector.replace(/^ns-/, '').replace(/^\[|\]$/g, '');
+        const distance = Math.min(levenshtein(q, bare), levenshtein(q, c.slug.toLowerCase()), levenshtein(q, c.className.toLowerCase()));
+        const substringBonus = bare.includes(q) || q.includes(bare) ? -2 : 0;
+        return { selector: c.selector, score: distance + substringBonus };
+    });
+    scored.sort((x, y) => x.score - y.score);
+    return scored.slice(0, limit).map((s) => s.selector);
+}
+function classNameToSelectorGuess(input) {
+    const match = /^Ns([A-Z][A-Za-z0-9]*)Component$/.exec(input.trim());
+    if (!match)
+        return null;
+    const kebab = match[1].replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+    return `ns-${kebab}`;
+}
+/**
+ * Resolves a user-supplied name to a `ComponentDoc`. Accepts a selector (`ns-button`), a class
+ * name (`NsButtonComponent`), a slug (`button`) or an attribute-directive selector
+ * (`[nsTooltip]`), case-insensitively. Never returns a bare "not found" -- always attaches
+ * distance-ranked suggestions.
+ */
+export function resolveComponent(snapshot, input) {
+    const trimmed = input.trim();
+    const lower = trimmed.toLowerCase();
+    const byExactSelector = snapshot.components.find((c) => c.selector === trimmed || c.selector === lower);
+    if (byExactSelector)
+        return { component: byExactSelector };
+    const byClassName = snapshot.components.find((c) => c.className.toLowerCase() === lower);
+    if (byClassName)
+        return { component: byClassName };
+    const bySlug = snapshot.components.find((c) => c.slug.toLowerCase() === lower);
+    if (bySlug)
+        return { component: bySlug };
+    const classNameGuess = classNameToSelectorGuess(trimmed);
+    if (classNameGuess) {
+        const found = snapshot.components.find((c) => c.selector === classNameGuess);
+        if (found)
+            return { component: found };
+    }
+    const bareGuess = lower.startsWith('ns-') || lower.startsWith('[') ? lower : `ns-${lower}`;
+    const byBareGuess = snapshot.components.find((c) => c.selector === bareGuess);
+    if (byBareGuess)
+        return { component: byBareGuess };
+    return {
+        component: null,
+        error: `No ng-solid component, directive or slug matches "${input}".`,
+        suggestions: suggestComponents(snapshot, trimmed)
+    };
+}
+/** For an internal (non-exported) subcomponent, finds the public component that renders it. */
+export function findPublicSiblingFor(snapshot, doc) {
+    const siblings = snapshot.components.filter((c) => c.visibility === 'public' && c.family === doc.family);
+    if (siblings.length === 0)
+        return null;
+    const exact = siblings.find((c) => c.selector === `ns-${doc.family}`);
+    if (exact)
+        return exact;
+    return [...siblings].sort((a, b) => a.selector.length - b.selector.length)[0];
+}
+function internalNotice(snapshot, doc) {
+    const publicSibling = findPublicSiblingFor(snapshot, doc);
+    return {
+        notice: `"${doc.selector}" is an internal subcomponent -- it is NOT exported from ` +
+            `@ng-solid/design-system's public barrel and cannot be used directly in a template. ` +
+            (publicSibling
+                ? `It is rendered internally by "${publicSibling.selector}"; use that component instead.`
+                : `It belongs to the "${doc.family}" feature; look for its public entry component.`),
+        publicAlternative: publicSibling ? importTrio(publicSibling) : null
+    };
+}
+function searchText(c) {
+    return [
+        c.selector,
+        c.slug,
+        c.className,
+        c.category,
+        c.summary,
+        c.family,
+        ...(c.variants ?? []),
+        ...(c.pitfalls ?? [])
+    ]
+        .filter(Boolean)
+        .join(' ')
+        .toLowerCase();
+}
+/** Generic fuzzy-by-name resolver for services/providers (both keyed by a PascalCase `name`). */
+function resolveByName(items, input, nameOf) {
+    const lower = input.trim().toLowerCase();
+    const normalize = (name) => name
+        .toLowerCase()
+        .replace(/^ns/, '')
+        .replace(/(service|component)$/, '');
+    const exact = items.find((item) => nameOf(item).toLowerCase() === lower);
+    if (exact)
+        return { item: exact };
+    const normalized = normalize(lower.startsWith('ns') ? lower : `ns${lower}`);
+    const byNormalized = items.find((item) => normalize(nameOf(item)) === normalized ||
+        normalize(nameOf(item)) === normalize(lower));
+    if (byNormalized)
+        return { item: byNormalized };
+    const scored = items
+        .map((item) => ({
+        item,
+        score: levenshtein(lower, nameOf(item).toLowerCase())
+    }))
+        .sort((a, b) => a.score - b.score)
+        .slice(0, 5)
+        .map(({ item }) => nameOf(item));
+    return { item: null, error: `No match for "${input}".`, suggestions: scored };
+}
+function placeholderValueFor(member) {
+    if (member.values && member.values.length > 0)
+        return member.values[0];
+    if (member.type.includes('number'))
+        return '0';
+    if (member.type === 'boolean')
+        return 'true';
+    return member.name;
+}
+/** Renders a single binding for a member, in the form an agent should actually write. */
+function bindingFor(member) {
+    if (member.kind === 'model')
+        return `[(${member.bindingName})]="${member.name}"`;
+    if (member.acceptsAttribute && member.type === 'boolean')
+        return member.bindingName;
+    if (member.values && member.values.length > 0)
+        return `${member.bindingName}="${member.values[0]}"`;
+    if (member.type === 'string')
+        return `${member.bindingName}="${placeholderValueFor(member)}"`;
+    return `[${member.bindingName}]="${member.name}"`;
+}
+/** Builds a minimal-but-valid markup snippet for a component, honoring required inputs/models. */
+export function buildTemplateSnippet(doc, options = {}) {
+    if (doc.snippet)
+        return doc.snippet;
+    const required = doc.inputs.filter((i) => i.required);
+    const optional = options.includeOptional
+        ? doc.inputs.filter((i) => !i.required).slice(0, 3)
+        : [];
+    const bindings = [...required, ...optional, ...doc.models].map(bindingFor);
+    const attrs = bindings.length > 0 ? ` ${bindings.join(' ')}` : '';
+    const hasDefaultSlot = doc.slots.some((slot) => slot.name === 'default');
+    return hasDefaultSlot
+        ? `<${doc.selector}${attrs}>Content</${doc.selector}>`
+        : `<${doc.selector}${attrs}></${doc.selector}>`;
+}
+function memberTable(members) {
+    if (members.length === 0)
+        return '_none_';
+    const rows = members.map((m) => {
+        const values = m.values ? m.values.map((v) => `\`${v}\``).join(', ') : '';
+        const inherited = m.inheritedFrom ? ` (from \`${m.inheritedFrom}\`)` : '';
+        return `| \`${m.bindingName}\` | \`${m.type}\` | ${m.required ? 'yes' : 'no'} | ${m.default ?? '-'} | ${values}${inherited} |`;
+    });
+    return [
+        '| Binding | Type | Required | Default | Values |',
+        '| --- | --- | --- | --- | --- |',
+        ...rows
+    ].join('\n');
+}
+/** Renders a full Markdown doc for a component -- shared by `export_component_docs` and the `ns://component/{selector}/markdown` resource. */
+export function renderComponentMarkdown(snapshot, doc) {
+    const trio = importTrio(doc);
+    const lines = [];
+    lines.push(`# \`${doc.selector}\` (${doc.className})`);
+    if (doc.visibility === 'internal') {
+        const notice = internalNotice(snapshot, doc);
+        lines.push('', `> **Internal.** ${notice.notice}`);
+    }
+    if (doc.summary)
+        lines.push('', doc.summary);
+    lines.push('', '## Import', '', '```ts', trio.importStatement, `imports: [${trio.imports.join(', ')}]`, '```');
+    lines.push('', '## Usage', '', '```html', buildTemplateSnippet(doc), '```');
+    lines.push('', '## Inputs', '', memberTable(doc.inputs));
+    lines.push('', '## Outputs', '', memberTable(doc.outputs));
+    lines.push('', '## Models', '', memberTable(doc.models));
+    if (doc.slots.length > 0) {
+        lines.push('', '## Slots', '', ...doc.slots.map((s) => `- \`${s.name}\`${s.select ? ` (\`select: ${s.select}\`)` : ''}`));
+    }
+    if (doc.a11y.ariaAttributes.length > 0 || doc.a11y.roles.length > 0) {
+        lines.push('', '## Accessibility');
+        if (doc.a11y.roles.length > 0)
+            lines.push(`- roles: ${doc.a11y.roles.map((r) => `\`${r}\``).join(', ')}`);
+        if (doc.a11y.ariaAttributes.length > 0)
+            lines.push(`- aria attributes: ${doc.a11y.ariaAttributes.map((a) => `\`${a}\``).join(', ')}`);
+    }
+    if (doc.tokens.length > 0) {
+        lines.push('', `## Style tokens (${doc.tokens.length})`, '', doc.tokens.map((t) => `- \`${t}\``).join('\n'));
+    }
+    if (doc.pitfalls && doc.pitfalls.length > 0) {
+        lines.push('', '## Pitfalls', '', ...doc.pitfalls.map((p) => `- ${p}`));
+    }
+    if (doc.relatedComponents && doc.relatedComponents.length > 0) {
+        lines.push('', '## Related', '', doc.relatedComponents.map((r) => `- \`${r}\``).join('\n'));
+    }
+    return lines.join('\n');
+}
+const API_SECTIONS = [
+    'inputs',
+    'outputs',
+    'models',
+    'slots',
+    'classes',
+    'a11y'
+];
+function apiSections(doc) {
+    return {
+        inputs: doc.inputs,
+        outputs: doc.outputs,
+        models: doc.models,
+        slots: doc.slots,
+        classes: doc.bem,
+        a11y: doc.a11y
+    };
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerComponentTools(server) {
+    // --- Discovery -----------------------------------------------------------
+    server.registerTool('list_components', {
+        title: 'List ng-solid components',
+        description: 'Lists ng-solid components/directives, optionally filtered by category, feature family or visibility. Defaults to public (exported) components only -- pass visibility: "all" to also see internal subcomponents.',
+        inputSchema: {
+            category: z
+                .string()
+                .optional()
+                .describe('Exact category name, e.g. "Formularios" (see get_categories).'),
+            family: z
+                .string()
+                .optional()
+                .describe('Feature directory, e.g. "input" or "modal" (see get_categories/list_components output).'),
+            visibility: z
+                .enum(['public', 'internal', 'all'])
+                .optional()
+                .describe('Defaults to "public".')
+        }
+    }, async ({ category, family, visibility }) => {
+        const snapshot = loadSnapshot();
+        const wanted = visibility ?? 'public';
+        const items = snapshot.components
+            .filter((c) => wanted === 'all' || c.visibility === wanted)
+            .filter((c) => !category || c.category === category)
+            .filter((c) => !family || c.family === family)
+            .map((c) => ({
+            selector: c.selector,
+            className: c.className,
+            slug: c.slug,
+            family: c.family,
+            group: c.group,
+            category: c.category ?? null,
+            summary: c.summary ?? null,
+            visibility: c.visibility
+        }));
+        return jsonResult({ count: items.length, components: items });
+    });
+    server.registerTool('get_component', {
+        title: 'Get a component doc',
+        description: 'Looks up one ng-solid component or directive by selector ("ns-button"), class name ("NsButtonComponent") or registry slug ("button") and returns its full documented API. The response always embeds the selector + importStatement + imports trio, since `<ns-button>` does not render without importing NsButtonComponent into a standalone component\'s `imports: [...]`. If the name resolves to an internal (non-exported) subcomponent, this returns an explanatory notice and the public component to use instead -- never a bare "not found". If nothing matches, returns ranked suggestions.',
+        inputSchema: {
+            component: z
+                .string()
+                .describe('Selector, class name or slug to resolve.')
+        }
+    }, async ({ component }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component) {
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        }
+        const doc = resolution.component;
+        if (doc.visibility === 'internal') {
+            return jsonResult({ ...internalNotice(snapshot, doc), component: doc });
+        }
+        return jsonResult({ ...importTrio(doc), component: doc });
+    });
+    server.registerTool('search_components', {
+        title: 'Search public components',
+        description: 'Full-text search over public component selectors, class names, categories, summaries, variants and known pitfalls.',
+        inputSchema: {
+            query: z.string().describe('Search term, e.g. "date" or "confirm".'),
+            limit: z.number().int().positive().max(50).optional()
+        }
+    }, async ({ query, limit }) => {
+        const snapshot = loadSnapshot();
+        const q = query.toLowerCase();
+        const matches = snapshot.components
+            .filter((c) => c.visibility === 'public')
+            .filter((c) => searchText(c).includes(q))
+            .slice(0, limit ?? 10)
+            .map((c) => ({
+            selector: c.selector,
+            className: c.className,
+            category: c.category ?? null,
+            summary: c.summary ?? null
+        }));
+        return jsonResult({ query, count: matches.length, components: matches });
+    });
+    server.registerTool('search_all', {
+        title: 'Search everything',
+        description: 'Broad search across public components, services, providers, guides and the icon catalog in one call.',
+        inputSchema: {
+            query: z.string(),
+            limit: z.number().int().positive().max(50).optional()
+        }
+    }, async ({ query, limit }) => {
+        const snapshot = loadSnapshot();
+        const n = limit ?? 5;
+        const q = query.toLowerCase();
+        const components = snapshot.components
+            .filter((c) => c.visibility === 'public' && searchText(c).includes(q))
+            .slice(0, n)
+            .map((c) => ({ selector: c.selector, summary: c.summary ?? null }));
+        const services = snapshot.services
+            .filter((s) => `${s.name} ${s.docs ?? ''}`.toLowerCase().includes(q))
+            .slice(0, n)
+            .map((s) => ({ name: s.name }));
+        const providers = snapshot.providers
+            .filter((p) => `${p.name} ${p.docs ?? ''}`.toLowerCase().includes(q))
+            .slice(0, n)
+            .map((p) => ({ name: p.name }));
+        const guides = snapshot.guides
+            .filter((g) => `${g.title} ${g.description ?? ''}`.toLowerCase().includes(q))
+            .slice(0, n)
+            .map((g) => ({ slug: g.slug }));
+        return jsonResult({ query, components, services, providers, guides });
+    });
+    server.registerTool('suggest_component', {
+        title: 'Suggest a component for an intent',
+        description: 'Given a natural-language description of a UI need ("confirm a destructive action", "pick a date range"), ranks public components by keyword overlap with their summary/category/variants. Returns the import trio for each suggestion.',
+        inputSchema: {
+            intent: z
+                .string()
+                .describe('What you are trying to build, in plain language.'),
+            limit: z.number().int().positive().max(10).optional()
+        }
+    }, async ({ intent, limit }) => {
+        const snapshot = loadSnapshot();
+        const words = intent
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length > 2);
+        const scored = snapshot.components
+            .filter((c) => c.visibility === 'public')
+            .map((c) => {
+            const text = searchText(c);
+            const score = words.reduce((acc, w) => acc + (text.includes(w) ? 1 : 0), 0);
+            return { c, score };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit ?? 5);
+        if (scored.length === 0) {
+            return jsonResult({
+                intent,
+                suggestions: [],
+                note: 'No component keyword-matched this intent. Try search_components with a narrower term, or list_categories to browse.'
+            });
+        }
+        return jsonResult({
+            intent,
+            suggestions: scored.map(({ c, score }) => ({
+                ...importTrio(c),
+                summary: c.summary ?? null,
+                category: c.category ?? null,
+                score
+            }))
+        });
+    });
+    server.registerTool('get_related_components', {
+        title: 'Get related components',
+        description: 'Returns components related to the given one via parent/child composition, curated cross-references, and shared feature family.',
+        inputSchema: { component: z.string() }
+    }, async ({ component }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        const related = new Set();
+        if (doc.composition.parent)
+            related.add(doc.composition.parent);
+        for (const child of doc.composition.children)
+            related.add(child);
+        for (const rel of doc.relatedComponents ?? [])
+            related.add(rel);
+        for (const sibling of snapshot.components) {
+            if (sibling.selector !== doc.selector && sibling.family === doc.family)
+                related.add(sibling.selector);
+        }
+        related.delete(doc.selector);
+        const resolved = [...related]
+            .map((selector) => snapshot.components.find((c) => c.selector === selector))
+            .filter((c) => Boolean(c));
+        return jsonResult({
+            component: doc.selector,
+            related: resolved.map((c) => ({
+                selector: c.selector,
+                className: c.className,
+                visibility: c.visibility,
+                summary: c.summary ?? null
+            }))
+        });
+    });
+    server.registerTool('get_categories', {
+        title: 'List categories',
+        description: 'Lists the docs categories (Spanish, as used by the demo app) with a public-component count for each.',
+        inputSchema: {}
+    }, async () => {
+        const snapshot = loadSnapshot();
+        const counts = new Map();
+        for (const c of snapshot.components) {
+            if (c.visibility !== 'public' || !c.category)
+                continue;
+            counts.set(c.category, (counts.get(c.category) ?? 0) + 1);
+        }
+        return jsonResult(snapshot.categories.map((category) => ({
+            category,
+            componentCount: counts.get(category) ?? 0
+        })));
+    });
+    // --- API -------------------------------------------------------------
+    server.registerTool('get_component_api', {
+        title: 'Get a component API slice',
+        description: "Returns a component's inputs/outputs/models/slots/BEM classes/accessibility metadata. Pass `section` to fetch only one slice (cheaper on context than get_component); omit it to get all six. Always includes the selector + importStatement + imports trio.",
+        inputSchema: {
+            component: z.string(),
+            section: z
+                .enum(API_SECTIONS)
+                .optional()
+                .describe('Restrict the response to one section; omit for all.')
+        }
+    }, async ({ component, section }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        const sections = apiSections(doc);
+        const payload = section ? { [section]: sections[section] } : sections;
+        const notice = doc.visibility === 'internal' ? internalNotice(snapshot, doc) : {};
+        return jsonResult({ ...importTrio(doc), ...notice, ...payload });
+    });
+    server.registerTool('get_component_import', {
+        title: 'Get the import trio for a component',
+        description: 'Returns exactly the selector + importStatement + imports array a standalone Angular component needs to render this ng-solid component.',
+        inputSchema: { component: z.string() }
+    }, async ({ component }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        return jsonResult({
+            ...importTrio(doc),
+            className: doc.className,
+            exportedAs: doc.exportedAs,
+            importFrom: doc.importFrom
+        });
+    });
+    server.registerTool('generate_component_template', {
+        title: 'Generate a markup template',
+        description: 'Generates a minimal-but-valid markup snippet for a component: every required input and model is bound with a placeholder of the correct shape (enum values use a real allowed value, never an invented one). Always includes the import trio.',
+        inputSchema: {
+            component: z.string(),
+            includeOptional: z
+                .boolean()
+                .optional()
+                .describe('Also bind up to 3 commonly-used optional inputs, not just required ones.')
+        }
+    }, async ({ component, includeOptional }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        const template = buildTemplateSnippet(doc, { includeOptional });
+        return jsonResult({
+            ...importTrio(doc),
+            template,
+            requiredInputs: doc.inputs
+                .filter((i) => i.required)
+                .map((i) => i.bindingName),
+            requiredModels: doc.models.map((m) => m.bindingName)
+        });
+    });
+    server.registerTool('get_usage_example', {
+        title: 'Get a usage example',
+        description: 'Returns the canonical docs-registry snippet for a component when one exists, falling back to a generated minimal template. Always includes the import trio.',
+        inputSchema: { component: z.string() }
+    }, async ({ component }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        return jsonResult({
+            ...importTrio(doc),
+            example: buildTemplateSnippet(doc),
+            fromRegistry: Boolean(doc.snippet)
+        });
+    });
+    server.registerTool('export_component_docs', {
+        title: 'Export full component documentation',
+        description: 'Exports the complete documentation for a component as Markdown (default, human/agent-readable) or as the raw JSON ComponentDoc.',
+        inputSchema: {
+            component: z.string(),
+            format: z.enum(['markdown', 'json']).optional()
+        }
+    }, async ({ component, format }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        if ((format ?? 'markdown') === 'json')
+            return jsonResult(doc);
+        return textResult(renderComponentMarkdown(snapshot, doc));
+    });
+    // --- Forms -------------------------------------------------------------
+    server.registerTool('get_form_control_contract', {
+        title: 'Get a form control contract',
+        description: 'For a component that implements ControlValueAccessor (works with formControlName / [(ngModel)]), returns its CVA contract: which inputs/outputs/models it inherits from the shared base class vs. declares itself.',
+        inputSchema: { component: z.string() }
+    }, async ({ component }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        if (!doc.formControl?.isValueAccessor) {
+            return jsonError({
+                error: `"${doc.selector}" is not a ControlValueAccessor (no formControl contract). Use get_component_api for its plain input/output API instead.`
+            });
+        }
+        const baseClass = doc.formControl.baseClass;
+        const isInherited = (m) => Boolean(baseClass) && m.inheritedFrom === baseClass;
+        return jsonResult({
+            ...importTrio(doc),
+            formControl: doc.formControl,
+            inherited: {
+                inputs: doc.inputs.filter(isInherited),
+                outputs: doc.outputs.filter(isInherited),
+                models: doc.models.filter(isInherited)
+            },
+            own: {
+                inputs: doc.inputs.filter((m) => !isInherited(m)),
+                outputs: doc.outputs.filter((m) => !isInherited(m)),
+                models: doc.models.filter((m) => !isInherited(m))
+            },
+            usage: {
+                reactiveForms: `<${doc.selector} formControlName="fieldName"></${doc.selector}>`,
+                modelBinding: `<${doc.selector} [(value)]="value"></${doc.selector}>`
+            }
+        });
+    });
+    server.registerTool('list_form_controls', {
+        title: 'List form controls',
+        description: 'Lists every public component that implements ControlValueAccessor (usable with formControlName / [(ngModel)]).',
+        inputSchema: {}
+    }, async () => {
+        const snapshot = loadSnapshot();
+        const controls = snapshot.components.filter((c) => c.visibility === 'public' && c.formControl?.isValueAccessor);
+        return jsonResult({
+            count: controls.length,
+            controls: controls.map((c) => ({
+                selector: c.selector,
+                className: c.className,
+                valueType: c.formControl?.valueType ?? null,
+                baseClass: c.formControl?.baseClass ?? null
+            }))
+        });
+    });
+    // --- Services & providers -------------------------------------------------
+    server.registerTool('list_services', {
+        title: 'List services',
+        description: 'Lists injectable ng-solid services (e.g. NsToastService, NsModalService) and the components each one manages.',
+        inputSchema: {}
+    }, async () => {
+        const snapshot = loadSnapshot();
+        return jsonResult(snapshot.services.map((s) => ({
+            name: s.name,
+            importFrom: s.importFrom,
+            providedIn: s.providedIn,
+            methodCount: s.methods.length,
+            relatedComponents: s.relatedComponents
+        })));
+    });
+    server.registerTool('get_service', {
+        title: 'Get a service',
+        description: 'Returns a service\'s full method signatures and an import statement, resolved fuzzily by name ("toast", "NsToastService", "ToastService" all work).',
+        inputSchema: { service: z.string() }
+    }, async ({ service }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveByName(snapshot.services, service, (s) => s.name);
+        if (!resolution.item)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        return jsonResult({
+            ...resolution.item,
+            importStatement: `import { ${resolution.item.name} } from '${resolution.item.importFrom}';`
+        });
+    });
+    server.registerTool('get_provider', {
+        title: 'Get a function provider',
+        description: 'Returns a function provider (provideNsTheme, provideIcons, provideIconsPatch) signature, docs and an example call for `appConfig.providers`.',
+        inputSchema: { provider: z.string() }
+    }, async ({ provider }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveByName(snapshot.providers, provider, (p) => p.name);
+        if (!resolution.item)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        return jsonResult({
+            ...resolution.item,
+            importStatement: `import { ${resolution.item.name} } from '${resolution.item.importFrom}';`
+        });
+    });
+    // --- Style contract & usage validation ------------------------------------
+    server.registerTool('get_style_contract', {
+        title: 'Get the style contract',
+        description: 'Returns the ng-solid style-architecture rules enforced by `pnpm quality:styles`: BEM naming, banned Tailwind utilities in markup, banned raw CSS values, required `@reference`, banned `@use`/`@import`.',
+        inputSchema: {}
+    }, async () => {
+        const snapshot = loadSnapshot();
+        if (!snapshot.styleContract)
+            return jsonError({
+                error: 'styleContract is missing from the snapshot.'
+            });
+        return jsonResult(snapshot.styleContract);
+    });
+    server.registerTool('validate_style_contract', {
+        title: 'Validate a code snippet against the style contract',
+        description: 'Runs the ng-solid style-architecture rules against a pasted snippet. `kind: "template"` checks markup for non-BEM classes and banned Tailwind utilities; `"scss"` checks a component stylesheet for missing `@reference`, banned `@use`/`@import`, and raw CSS values instead of `--ns-component-*` tokens; `"component-ts"` checks a component source for inline `styles:` (plus its inline template, if any).',
+        inputSchema: {
+            code: z.string(),
+            kind: z.enum([
+                'template',
+                'scss',
+                'component-ts'
+            ])
+        }
+    }, async ({ code, kind }) => {
+        const snapshot = loadSnapshot();
+        if (!snapshot.styleContract)
+            return jsonError({
+                error: 'styleContract is missing from the snapshot.'
+            });
+        return jsonResult(validateStyleContract(code, kind, snapshot.styleContract));
+    });
+    server.registerTool('validate_component_usage', {
+        title: 'Validate component usage in a template',
+        description: 'The most valuable check in this server: validates a markup snippet against a component\'s REAL API from the AST-derived snapshot. Catches unknown inputs/outputs/models (respecting aliases like nsTooltip/maxlength/nsField), invalid enum values (e.g. `variant="warning"` on ns-button, which only accepts 5 values), invented BEM modifier classes, and a missing `imports: [...]` declaration. Every failure includes the correct alternative, never just a bare failure.',
+        inputSchema: {
+            component: z.string(),
+            template: z.string().describe('The markup to validate.'),
+            imports: z
+                .array(z.string())
+                .optional()
+                .describe("Class names already present in this file's `imports: [...]` array, to verify the component is actually importable. Omit to skip this check.")
+        }
+    }, async ({ component, template, imports }) => {
+        const snapshot = loadSnapshot();
+        const resolution = resolveComponent(snapshot, component);
+        if (!resolution.component)
+            return jsonError({
+                error: resolution.error,
+                suggestions: resolution.suggestions
+            });
+        const doc = resolution.component;
+        const inputByBinding = new Map(doc.inputs.map((i) => [i.bindingName, i]));
+        const outputByBinding = new Map(doc.outputs.map((o) => [o.bindingName, o]));
+        const modelByBinding = new Map(doc.models.map((m) => [m.bindingName, m]));
+        const { attributes, events, models } = parseTemplateCandidates(template);
+        const eventNames = new Set(events);
+        // ns-prefixed candidates are excluded from the invalid-props pool: they are almost always
+        // scanner noise (a selector fragment or an aliased-input binding, e.g. nsTooltip/nsField,
+        // which -- if genuinely used -- already resolves via inputByBinding). Ported from BHD's
+        // equivalent `bhd`-prefix filter.
+        const attributeCandidates = [...new Set(attributes)].filter((name) => !eventNames.has(name) && !name.startsWith('ns'));
+        const unknownInputs = attributeCandidates.filter((name) => !inputByBinding.has(name));
+        const unknownOutputs = [...new Set(events)].filter((name) => !outputByBinding.has(name));
+        const unknownModels = [...new Set(models)].filter((name) => !modelByBinding.has(name));
+        const invalidValues = [];
+        for (const match of template.matchAll(/([a-zA-Z][\w-]*)\s*=\s*"([^"]*)"/g)) {
+            const [, name, value] = match;
+            const input = inputByBinding.get(name);
+            if (input?.values &&
+                input.values.length > 0 &&
+                !input.values.includes(value)) {
+                invalidValues.push({
+                    input: name,
+                    value,
+                    allowed: input.values,
+                    label: `${name}=${value}`
+                });
+            }
+        }
+        const knownClasses = new Set([
+            doc.bem.block,
+            ...doc.bem.staticClasses,
+            ...doc.bem.elements,
+            ...doc.bem.modifiers.map((m) => m.className)
+        ]);
+        const invalidClasses = [];
+        for (const match of template.matchAll(/(?:^|\s)class="([^"]+)"/g)) {
+            for (const cls of match[1].trim().split(/\s+/)) {
+                if (cls.startsWith(`${doc.bem.block}--`) && !knownClasses.has(cls))
+                    invalidClasses.push(cls);
+            }
+        }
+        const styleResult = snapshot.styleContract
+            ? validateStyleContract(template, 'template', snapshot.styleContract)
+            : null;
+        const styleErrors = (styleResult?.violations ?? []).filter((v) => v.severity === 'error');
+        const importDeclared = imports === undefined ? null : imports.includes(doc.className);
+        const suggestions = [];
+        for (const name of unknownInputs) {
+            const closest = [...inputByBinding.keys()].sort((a, b) => levenshtein(name, a) - levenshtein(name, b))[0];
+            if (closest)
+                suggestions.push(`Unknown input "${name}" -- did you mean "${closest}"?`);
+        }
+        for (const name of unknownOutputs) {
+            const closest = [...outputByBinding.keys()].sort((a, b) => levenshtein(name, a) - levenshtein(name, b))[0];
+            if (closest)
+                suggestions.push(`Unknown output "${name}" -- did you mean "(${closest})"?`);
+        }
+        for (const v of invalidValues) {
+            suggestions.push(`"${v.input}" only accepts ${v.allowed.map((a) => `"${a}"`).join(', ')} -- "${v.value}" is not valid.`);
+        }
+        if (importDeclared === false) {
+            suggestions.push(`"${doc.className}" is missing from imports: [...] -- add it or "${doc.selector}" will not render.`);
+        }
+        const valid = unknownInputs.length === 0 &&
+            unknownOutputs.length === 0 &&
+            unknownModels.length === 0 &&
+            invalidValues.length === 0 &&
+            invalidClasses.length === 0 &&
+            styleErrors.length === 0 &&
+            importDeclared !== false;
+        return jsonResult({
+            component: doc.selector,
+            valid,
+            unknownInputs,
+            unknownOutputs,
+            unknownModels,
+            invalidValues,
+            invalidClasses,
+            styleViolations: styleResult?.violations ?? [],
+            importDeclared,
+            suggestions
+        });
+    });
+}
+//# sourceMappingURL=tools.components.js.map